Skip to content

dtype

zarr.dtype

Bool dataclass

Bases: ZDType[BoolDType, bool_], 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_name (Literal["bool"] = "bool") –

    The Zarr v3 name of the dtype.

  • _zarr_v2_name (``Literal["|b1"]`` = ``"|b1"``) –

    The Zarr v2 name of the dtype, which is also a string representation of the boolean dtype used by NumPy.

  • dtype_cls (ClassVar[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 V2and Zarr V3 specification documents for details.

Source code in zarr/core/dtype/npy/bool.py 
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
@dataclass(frozen=True, kw_only=True, slots=True)
class Bool(ZDType[np.dtypes.BoolDType, np.bool_], HasItemSize):
    """
    A Zarr data type for arrays containing booleans.

    Wraps the [`np.dtypes.BoolDType`][numpy.dtypes.BoolDType] data type. Scalars for this data type are instances of
    [`np.bool_`][numpy.bool_].

    Attributes
    ----------

    _zarr_v3_name : Literal["bool"] = "bool"
        The Zarr v3 name of the dtype.
    _zarr_v2_name : ``Literal["|b1"]`` = ``"|b1"``
        The Zarr v2 name of the dtype, which is also a string representation
        of the boolean dtype used by NumPy.
    dtype_cls : ClassVar[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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding)and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
    """

    _zarr_v3_name: ClassVar[Literal["bool"]] = "bool"
    _zarr_v2_name: ClassVar[Literal["|b1"]] = "|b1"
    dtype_cls = np.dtypes.BoolDType

    @classmethod
    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
        """
        Create an instance of Bool from an instance of np.dtypes.BoolDType.

        Parameters
        ----------
        dtype : TBaseDType
            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.
        """
        if cls._check_native_dtype(dtype):
            return cls()
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    def to_native_dtype(self: Self) -> np.dtypes.BoolDType:
        """
        Create a NumPy boolean dtype instance from this ZDType.

        Returns
        -------
        np.dtypes.BoolDType
            The NumPy boolean dtype.
        """
        return self.dtype_cls()

    @classmethod
    def _check_json_v2(
        cls,
        data: DTypeJSON,
    ) -> TypeGuard[DTypeConfig_V2[Literal["|b1"], None]]:
        """
        Check that the input is a valid JSON representation of a Bool.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to check.

        Returns
        -------
        ``TypeGuard[DTypeConfig_V2[Literal["|b1"], None]]``
            True if the input is a valid JSON representation, False otherwise.
        """
        return (
            check_dtype_spec_v2(data)
            and data["name"] == cls._zarr_v2_name
            and data["object_codec_id"] is None
        )

    @classmethod
    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[Literal["bool"]]:
        """
        Check that the input is a valid JSON representation of this class in Zarr V3.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to check.

        Returns
        -------
        bool
            True if the input is a valid JSON representation, False otherwise.
        """
        return data == cls._zarr_v3_name

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of Bool from Zarr V2-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Bool
            An instance of Bool.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class.
        """
        if cls._check_json_v2(data):
            return cls()
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v2_name!r}"
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls: type[Self], data: DTypeJSON) -> Self:
        """
        Create an instance of Bool from Zarr V3-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Bool
            An instance of Bool.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class.
        """
        if cls._check_json_v3(data):
            return cls()
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal["|b1"], None]: ...

    @overload
    def to_json(self, zarr_format: Literal[3]) -> Literal["bool"]: ...

    def to_json(
        self, zarr_format: ZarrFormat
    ) -> DTypeConfig_V2[Literal["|b1"], None] | Literal["bool"]:
        """
        Serialize this Bool instance to JSON.

        Parameters
        ----------
        zarr_format : ZarrFormat
            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.
        """
        if zarr_format == 2:
            return {"name": self._zarr_v2_name, "object_codec_id": None}
        elif zarr_format == 3:
            return self._zarr_v3_name
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    def _check_scalar(self, data: object) -> bool:
        """
        Check if the input can be cast to a boolean scalar.

        Parameters
        ----------
        data : object
            The data to check.

        Returns
        -------
        bool
            True if the input can be cast to a boolean scalar, False otherwise.
        """
        return True

    def cast_scalar(self, data: object) -> np.bool_:
        """
        Cast the input to a numpy boolean scalar.

        Parameters
        ----------
        data : object
            The data to cast.

        Returns
        -------
        bool : np.bool_
            The numpy boolean scalar.

        Raises
        ------
        TypeError
            If the input cannot be converted to a numpy boolean.
        """
        if self._check_scalar(data):
            return np.bool_(data)
        msg = (  # pragma: no cover
            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
            f"data type {self}."
        )
        raise TypeError(msg)  # pragma: no cover

    def default_scalar(self) -> np.bool_:
        """
        Get the default value for the boolean dtype.

        Returns
        -------
        bool : np.bool_
            The default value.
        """
        return np.False_

    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> bool:
        """
        Convert a scalar to a python bool.

        Parameters
        ----------
        data : object
            The value to convert.
        zarr_format : ZarrFormat
            The zarr format version.

        Returns
        -------
        bool
            The JSON-serializable format.
        """
        return bool(data)

    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.bool_:
        """
        Read a JSON-serializable value as a numpy boolean scalar.

        Parameters
        ----------
        data : JSON
            The JSON-serializable value.
        zarr_format : ZarrFormat
            The zarr format version.

        Returns
        -------
        bool : np.bool_
            The numpy boolean scalar.

        Raises
        ------
        TypeError
            If the input is not a valid boolean type.
        """
        if self._check_scalar(data):
            return np.bool_(data)
        raise TypeError(f"Invalid type: {data}. Expected a boolean.")  # pragma: no cover

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 1

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> bool_

Cast the input to a numpy boolean scalar.

Parameters:

  • data (object) –

    The data to cast.

Returns:

  • bool ( bool_ ) –

    The numpy boolean scalar.

Raises:

  • TypeError –

    If the input cannot be converted to a numpy boolean.

Source code in zarr/core/dtype/npy/bool.py 
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
def cast_scalar(self, data: object) -> np.bool_:
    """
    Cast the input to a numpy boolean scalar.

    Parameters
    ----------
    data : object
        The data to cast.

    Returns
    -------
    bool : np.bool_
        The numpy boolean scalar.

    Raises
    ------
    TypeError
        If the input cannot be converted to a numpy boolean.
    """
    if self._check_scalar(data):
        return np.bool_(data)
    msg = (  # pragma: no cover
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)  # pragma: no cover

default_scalar 

default_scalar() -> bool_

Get the default value for the boolean dtype.

Returns:

  • bool ( bool_ ) –

    The default value.

Source code in zarr/core/dtype/npy/bool.py 
255
256
257
258
259
260
261
262
263
264
def default_scalar(self) -> np.bool_:
    """
    Get the default value for the boolean dtype.

    Returns
    -------
    bool : np.bool_
        The default value.
    """
    return np.False_

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> bool_

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • bool ( bool_ ) –

    The numpy boolean scalar.

Raises:

  • TypeError –

    If the input is not a valid boolean type.

Source code in zarr/core/dtype/npy/bool.py 
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.bool_:
    """
    Read a JSON-serializable value as a numpy boolean scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    bool : np.bool_
        The numpy boolean scalar.

    Raises
    ------
    TypeError
        If the input is not a valid boolean type.
    """
    if self._check_scalar(data):
        return np.bool_(data)
    raise TypeError(f"Invalid type: {data}. Expected a boolean.")  # pragma: no cover

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (TBaseDType) –

    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.

Source code in zarr/core/dtype/npy/bool.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an instance of Bool from an instance of np.dtypes.BoolDType.

    Parameters
    ----------
    dtype : TBaseDType
        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.
    """
    if cls._check_native_dtype(dtype):
        return cls()
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[Literal["|b1"], None]

to_json(zarr_format: Literal[3]) -> Literal['bool']

to_json(
    zarr_format: ZarrFormat,
) -> DTypeConfig_V2[Literal["|b1"], None] | Literal["bool"]

Serialize this Bool instance to JSON.

Parameters:

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/npy/bool.py 
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
def to_json(
    self, zarr_format: ZarrFormat
) -> DTypeConfig_V2[Literal["|b1"], None] | Literal["bool"]:
    """
    Serialize this Bool instance to JSON.

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        return {"name": self._zarr_v2_name, "object_codec_id": None}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> bool

Convert a scalar to a python bool.

Parameters:

  • data (object) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • bool –

    The JSON-serializable format.

Source code in zarr/core/dtype/npy/bool.py 
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> bool:
    """
    Convert a scalar to a python bool.

    Parameters
    ----------
    data : object
        The value to convert.
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    bool
        The JSON-serializable format.
    """
    return bool(data)

to_native_dtype 

to_native_dtype() -> BoolDType

Create a NumPy boolean dtype instance from this ZDType.

Returns:

Source code in zarr/core/dtype/npy/bool.py 
77
78
79
80
81
82
83
84
85
86
def to_native_dtype(self: Self) -> np.dtypes.BoolDType:
    """
    Create a NumPy boolean dtype instance from this ZDType.

    Returns
    -------
    np.dtypes.BoolDType
        The NumPy boolean dtype.
    """
    return self.dtype_cls()

Complex128 dataclass

Bases: BaseComplex[Complex128DType, complex128], 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:

Source code in zarr/core/dtype/npy/complex.py 
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
@dataclass(frozen=True, kw_only=True)
class Complex128(BaseComplex[np.dtypes.Complex128DType, np.complex128], HasEndianness):
    """
    A Zarr data type for arrays containing 64 bit complex floats.

    Wraps the [`np.dtypes.Complex128DType`][numpy.dtypes.Complex128DType] data type. Scalars for this data type
    are instances of [`np.complex128`][numpy.complex128].

    Attributes
    ----------
    dtype_cls : Type[np.dtypes.Complex128DType]
        The numpy dtype class for this data type.
    _zarr_v3_name : ClassVar[Literal["complex128"]]
        The name of this data type in Zarr V3.
    _zarr_v2_names : ClassVar[tuple[Literal[">c16"], Literal["<c16"]]]
        The names of this data type in Zarr V2.
    """

    dtype_cls = np.dtypes.Complex128DType
    _zarr_v3_name: ClassVar[Literal["complex128"]] = "complex128"
    _zarr_v2_names: ClassVar[tuple[Literal[">c16"], Literal["<c16"]]] = (">c16", "<c16")

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 16

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> TComplexScalar_co

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

Parameters:

  • data (object) –

    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.

Source code in zarr/core/dtype/npy/complex.py 
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
def cast_scalar(self, data: object) -> TComplexScalar_co:
    """
    Attempt to cast a given object to a numpy complex scalar.

    Parameters
    ----------
    data : object
        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.
    """
    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> TComplexScalar_co

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

Returns:

  • Int scalar –

    The default value.

Source code in zarr/core/dtype/npy/complex.py 
286
287
288
289
290
291
292
293
294
295
def default_scalar(self) -> TComplexScalar_co:
    """
    Get the default value, which is 0 cast to this dtype

    Returns
    -------
    Int scalar
        The default value.
    """
    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TComplexScalar_co

Read a JSON-serializable value as a numpy float.

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • TScalar_co –

    The numpy float.

Source code in zarr/core/dtype/npy/complex.py 
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TComplexScalar_co:
    """
    Read a JSON-serializable value as a numpy float.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    TScalar_co
        The numpy float.
    """
    if zarr_format == 2:
        if check_json_complex_float_v2(data):
            return self._cast_scalar_unchecked(complex_float_from_json_v2(data))
        raise TypeError(
            f"Invalid type: {data}. Expected a float or a special string encoding of a float."
        )
    elif zarr_format == 3:
        if check_json_complex_float_v3(data):
            return self._cast_scalar_unchecked(complex_float_from_json_v3(data))
        raise TypeError(
            f"Invalid type: {data}. Expected a float or a special string encoding of a float."
        )
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (TBaseDType) –

    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.

Source code in zarr/core/dtype/npy/complex.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an instance of this data type from a NumPy complex dtype.

    Parameters
    ----------
    dtype : TBaseDType
        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.
    """
    if cls._check_native_dtype(dtype):
        return cls(endianness=get_endianness_from_numpy_dtype(dtype))
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[str, None]

to_json(zarr_format: Literal[3]) -> str

to_json(
    zarr_format: ZarrFormat,
) -> DTypeConfig_V2[str, None] | str

Serialize this object to a JSON-serializable representation.

Parameters:

  • zarr_format (ZarrFormat) –

    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:

Source code in zarr/core/dtype/npy/complex.py 
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
def to_json(self, zarr_format: ZarrFormat) -> DTypeConfig_V2[str, None] | str:
    """
    Serialize this object to a JSON-serializable representation.

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """

    if zarr_format == 2:
        return {"name": self.to_native_dtype().str, "object_codec_id": None}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> JSON

Convert an object to a JSON-serializable float.

Parameters:

  • data (_BaseScalar) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/npy/complex.py 
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> JSON:
    """
    Convert an object to a JSON-serializable float.

    Parameters
    ----------
    data : _BaseScalar
        The value to convert.
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        return complex_float_to_json_v2(self.cast_scalar(data))
    elif zarr_format == 3:
        return complex_float_to_json_v3(self.cast_scalar(data))
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_native_dtype 

to_native_dtype() -> 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.

Source code in zarr/core/dtype/npy/complex.py 
77
78
79
80
81
82
83
84
85
86
87
88
def to_native_dtype(self) -> 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.
    """

    byte_order = endianness_to_numpy_str(self.endianness)
    return self.dtype_cls().newbyteorder(byte_order)  # type: ignore[return-value]

Complex64 dataclass

Bases: BaseComplex[Complex64DType, 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:

Source code in zarr/core/dtype/npy/complex.py 
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
@dataclass(frozen=True, kw_only=True)
class Complex64(BaseComplex[np.dtypes.Complex64DType, np.complex64]):
    """
    A Zarr data type for arrays containing 64 bit complex floats.

    Wraps the [`np.dtypes.Complex64DType`][numpy.dtypes.Complex64DType] data type. Scalars for this data type
    are instances of [`np.complex64`][numpy.complex64].

    Attributes
    ----------
    dtype_cls : Type[np.dtypes.Complex64DType]
        The numpy dtype class for this data type.
    _zarr_v3_name : ClassVar[Literal["complex64"]]
        The name of this data type in Zarr V3.
    _zarr_v2_names : ClassVar[tuple[Literal[">c8"], Literal["<c8"]]]
        The names of this data type in Zarr V2.
    """

    dtype_cls = np.dtypes.Complex64DType
    _zarr_v3_name: ClassVar[Literal["complex64"]] = "complex64"
    _zarr_v2_names: ClassVar[tuple[Literal[">c8"], Literal["<c8"]]] = (">c8", "<c8")

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 8

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> TComplexScalar_co

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

Parameters:

  • data (object) –

    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.

Source code in zarr/core/dtype/npy/complex.py 
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
def cast_scalar(self, data: object) -> TComplexScalar_co:
    """
    Attempt to cast a given object to a numpy complex scalar.

    Parameters
    ----------
    data : object
        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.
    """
    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> TComplexScalar_co

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

Returns:

  • Int scalar –

    The default value.

Source code in zarr/core/dtype/npy/complex.py 
286
287
288
289
290
291
292
293
294
295
def default_scalar(self) -> TComplexScalar_co:
    """
    Get the default value, which is 0 cast to this dtype

    Returns
    -------
    Int scalar
        The default value.
    """
    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TComplexScalar_co

Read a JSON-serializable value as a numpy float.

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • TScalar_co –

    The numpy float.

Source code in zarr/core/dtype/npy/complex.py 
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TComplexScalar_co:
    """
    Read a JSON-serializable value as a numpy float.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    TScalar_co
        The numpy float.
    """
    if zarr_format == 2:
        if check_json_complex_float_v2(data):
            return self._cast_scalar_unchecked(complex_float_from_json_v2(data))
        raise TypeError(
            f"Invalid type: {data}. Expected a float or a special string encoding of a float."
        )
    elif zarr_format == 3:
        if check_json_complex_float_v3(data):
            return self._cast_scalar_unchecked(complex_float_from_json_v3(data))
        raise TypeError(
            f"Invalid type: {data}. Expected a float or a special string encoding of a float."
        )
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (TBaseDType) –

    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.

Source code in zarr/core/dtype/npy/complex.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an instance of this data type from a NumPy complex dtype.

    Parameters
    ----------
    dtype : TBaseDType
        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.
    """
    if cls._check_native_dtype(dtype):
        return cls(endianness=get_endianness_from_numpy_dtype(dtype))
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[str, None]

to_json(zarr_format: Literal[3]) -> str

to_json(
    zarr_format: ZarrFormat,
) -> DTypeConfig_V2[str, None] | str

Serialize this object to a JSON-serializable representation.

Parameters:

  • zarr_format (ZarrFormat) –

    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:

Source code in zarr/core/dtype/npy/complex.py 
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
def to_json(self, zarr_format: ZarrFormat) -> DTypeConfig_V2[str, None] | str:
    """
    Serialize this object to a JSON-serializable representation.

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """

    if zarr_format == 2:
        return {"name": self.to_native_dtype().str, "object_codec_id": None}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> JSON

Convert an object to a JSON-serializable float.

Parameters:

  • data (_BaseScalar) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/npy/complex.py 
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> JSON:
    """
    Convert an object to a JSON-serializable float.

    Parameters
    ----------
    data : _BaseScalar
        The value to convert.
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        return complex_float_to_json_v2(self.cast_scalar(data))
    elif zarr_format == 3:
        return complex_float_to_json_v3(self.cast_scalar(data))
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_native_dtype 

to_native_dtype() -> 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.

Source code in zarr/core/dtype/npy/complex.py 
77
78
79
80
81
82
83
84
85
86
87
88
def to_native_dtype(self) -> 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.
    """

    byte_order = endianness_to_numpy_str(self.endianness)
    return self.dtype_cls().newbyteorder(byte_order)  # type: ignore[return-value]

DateTime64 dataclass

Bases: TimeDTypeBase[DateTime64DType, datetime64], 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_cls (Type[dtypesTimeDelta64DType]) –

    The numpy dtype class for this data type.

  • unit (DateTimeUnit) –

    The unit of time for this data type.

  • scale_factor (int) –

    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

Source code in zarr/core/dtype/npy/time.py 
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
@dataclass(frozen=True, kw_only=True, slots=True)
class DateTime64(TimeDTypeBase[np.dtypes.DateTime64DType, np.datetime64], 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_cls : Type[np.dtypesTimeDelta64DType]
        The numpy dtype class for this data type.
    unit : DateTimeUnit
        The unit of time for this data type.
    scale_factor : int
        The scale factor for the time unit.

    References
    ----------
    The Zarr V2 representation of this data type is defined in the Zarr V2
    [specification document](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

    The Zarr V3 representation of this data type is defined in the ``numpy.datetime64``
    [specification document](https://github.com/zarr-developers/zarr-extensions/tree/main/data-types/numpy.datetime64)
    """

    dtype_cls = np.dtypes.DateTime64DType  # type: ignore[assignment]
    _zarr_v3_name: ClassVar[Literal["numpy.datetime64"]] = "numpy.datetime64"
    _zarr_v2_names: ClassVar[tuple[Literal[">M8"], Literal["<M8"]]] = (">M8", "<M8")
    _numpy_name: ClassVar[Literal["datetime64"]] = "datetime64"
    unit: DateTimeUnit = "generic"
    scale_factor: int = 1

    @classmethod
    def _check_json_v2(cls, data: DTypeJSON) -> TypeGuard[DateTime64JSON_V2]:
        """
        Check that the input is a valid JSON representation of this data type.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to check.

        Returns
        -------
        TypeGuard[DateTime64JSON_V2]
            True if the input is a valid JSON representation of a NumPy datetime64 data type,
            otherwise False.
        """
        if not check_dtype_spec_v2(data):
            return False
        name = data["name"]
        if not isinstance(name, str):
            return False
        if not name.startswith(cls._zarr_v2_names):
            return False
        if len(name) == 3:
            # no unit, and
            # we already checked that this string is either <M8 or >M8
            return True
        else:
            return name[4:-1].endswith(DATETIME_UNIT) and name[-1] == "]"

    @classmethod
    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[DateTime64JSON_V3]:
        """
        Check that the input is a valid JSON representation of this class in Zarr V3.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to check.

        Returns
        -------
        TypeGuard[DateTime64JSON_V3]
            True if the input is a valid JSON representation of a numpy datetime64 data type in Zarr V3, False otherwise.
        """

        return (
            isinstance(data, dict)
            and set(data.keys()) == {"name", "configuration"}
            and data["name"] == cls._zarr_v3_name
            and isinstance(data["configuration"], dict)
            and set(data["configuration"].keys()) == {"unit", "scale_factor"}
        )

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from a Zarr V2-flavored JSON representation.

        This method checks if the provided JSON data is a valid representation of this class.
        If valid, it creates an instance using the native NumPy dtype. Otherwise, it raises a
        DataTypeValidationError.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to parse.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class.
        """

        if cls._check_json_v2(data):
            name = data["name"]
            return cls.from_native_dtype(np.dtype(name))
        msg = (
            f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a string "
            f"representation of an instance of {cls.dtype_cls}"
        )
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from a Zarr V3-flavored JSON representation.

        This method checks if the provided JSON data is a valid representation of this class.
        If valid, it creates an instance using the native NumPy dtype. Otherwise, it raises a
        DataTypeValidationError.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to parse.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class.
        """
        if cls._check_json_v3(data):
            unit = data["configuration"]["unit"]
            scale_factor = data["configuration"]["scale_factor"]
            return cls(unit=unit, scale_factor=scale_factor)
        msg = (
            f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a dict "
            f"with a 'name' key with the value 'numpy.datetime64', "
            "and a 'configuration' key with a value of a dict with a 'unit' key and a "
            "'scale_factor' key"
        )
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> DateTime64JSON_V2: ...
    @overload
    def to_json(self, zarr_format: Literal[3]) -> DateTime64JSON_V3: ...

    def to_json(self, zarr_format: ZarrFormat) -> DateTime64JSON_V2 | DateTime64JSON_V3:
        """
        Serialize this data type to JSON.

        Parameters
        ----------
        zarr_format : ZarrFormat
            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.
        """
        if zarr_format == 2:
            name = self.to_native_dtype().str
            return {"name": name, "object_codec_id": None}
        elif zarr_format == 3:
            return {
                "name": self._zarr_v3_name,
                "configuration": {"unit": self.unit, "scale_factor": self.scale_factor},
            }
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    def _check_scalar(self, data: object) -> TypeGuard[DateTimeLike]:
        """
        Check if the input is convertible to a scalar of this data type.

        Parameters
        ----------
        data : object
            The object to check.

        Returns
        -------
        TypeGuard[DateTimeLike]
            True if the input is a scalar of this data type, False otherwise.
        """
        if data is None:
            return True
        return isinstance(data, str | int | bytes | np.datetime64 | datetime)

    def _cast_scalar_unchecked(self, data: DateTimeLike) -> np.datetime64:
        """
        Cast the input to a scalar of this data type without any type checking.

        Parameters
        ----------
        data : DateTimeLike
            The scalar data to cast.

        Returns
        -------
        numpy.datetime64
            The input cast to a NumPy datetime scalar.
        """
        return self.to_native_dtype().type(data, f"{self.scale_factor}{self.unit}")

    def cast_scalar(self, data: object) -> np.datetime64:
        """
        Cast the input to a scalar of this data type after a type check.

        Parameters
        ----------
        data : object
            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.
        """
        if self._check_scalar(data):
            return self._cast_scalar_unchecked(data)
        msg = (
            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
            f"data type {self}."
        )
        raise TypeError(msg)

    def default_scalar(self) -> np.datetime64:
        """
        Return the default scalar value for this data type.

        Returns
        -------
        numpy.datetime64
            The default scalar value, which is a 'Not-a-Time' (NaT) value
        """

        return np.datetime64("NaT")

    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.datetime64:
        """
        Read a JSON-serializable value as a scalar.

        Parameters
        ----------
        data : JSON
            The JSON-serializable value.
        zarr_format : ZarrFormat
            The zarr format version.

        Returns
        -------
        numpy.datetime64
            The numpy datetime scalar.

        Raises
        ------
        TypeError
            If the input is not a valid integer type.
        """
        if check_json_time(data):
            return self._cast_scalar_unchecked(data)
        raise TypeError(f"Invalid type: {data}. Expected an integer.")  # pragma: no cover

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> datetime64

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

Parameters:

  • data (object) –

    The scalar value to cast.

Returns:

  • datetime64 –

    The input cast to a NumPy datetime scalar.

Raises:

  • TypeError –

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

Source code in zarr/core/dtype/npy/time.py 
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
def cast_scalar(self, data: object) -> np.datetime64:
    """
    Cast the input to a scalar of this data type after a type check.

    Parameters
    ----------
    data : object
        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.
    """
    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> datetime64

Return the default scalar value for this data type.

Returns:

  • datetime64 –

    The default scalar value, which is a 'Not-a-Time' (NaT) value

Source code in zarr/core/dtype/npy/time.py 
850
851
852
853
854
855
856
857
858
859
860
def default_scalar(self) -> np.datetime64:
    """
    Return the default scalar value for this data type.

    Returns
    -------
    numpy.datetime64
        The default scalar value, which is a 'Not-a-Time' (NaT) value
    """

    return np.datetime64("NaT")

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> datetime64

Read a JSON-serializable value as a scalar.

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

Raises:

  • TypeError –

    If the input is not a valid integer type.

Source code in zarr/core/dtype/npy/time.py 
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.datetime64:
    """
    Read a JSON-serializable value as a scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    numpy.datetime64
        The numpy datetime scalar.

    Raises
    ------
    TypeError
        If the input is not a valid integer type.
    """
    if check_json_time(data):
        return self._cast_scalar_unchecked(data)
    raise TypeError(f"Invalid type: {data}. Expected an integer.")  # pragma: no cover

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (TBaseDType) –

    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.

Source code in zarr/core/dtype/npy/time.py 
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an instance of this class from a native NumPy data type.

    Parameters
    ----------
    dtype : TBaseDType
        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.
    """

    if cls._check_native_dtype(dtype):
        unit, scale_factor = np.datetime_data(dtype.name)
        unit = cast("DateTimeUnit", unit)
        return cls(
            unit=unit,
            scale_factor=scale_factor,
            endianness=get_endianness_from_numpy_dtype(dtype),
        )
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(zarr_format: Literal[2]) -> DateTime64JSON_V2

to_json(zarr_format: Literal[3]) -> DateTime64JSON_V3

to_json(
    zarr_format: ZarrFormat,
) -> DateTime64JSON_V2 | DateTime64JSON_V3

Serialize this data type to JSON.

Parameters:

  • zarr_format (ZarrFormat) –

    The Zarr format version (2 or 3).

Returns:

Raises:

  • ValueError –

    If the zarr_format is not 2 or 3.

Source code in zarr/core/dtype/npy/time.py 
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
def to_json(self, zarr_format: ZarrFormat) -> DateTime64JSON_V2 | DateTime64JSON_V3:
    """
    Serialize this data type to JSON.

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        name = self.to_native_dtype().str
        return {"name": name, "object_codec_id": None}
    elif zarr_format == 3:
        return {
            "name": self._zarr_v3_name,
            "configuration": {"unit": self.unit, "scale_factor": self.scale_factor},
        }
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> int

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

Parameters:

  • data (object) –

    The python object to convert.

  • zarr_format (ZarrFormat) –

    The Zarr format version (2 or 3).

Returns:

  • int –

    The JSON representation of the scalar.

Source code in zarr/core/dtype/npy/time.py 
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
    """
    Convert a python object to a JSON representation of a datetime64 or timedelta64 scalar.

    Parameters
    ----------
    data : object
        The python object to convert.
    zarr_format : ZarrFormat
        The Zarr format version (2 or 3).

    Returns
    -------
    int
        The JSON representation of the scalar.
    """
    return datetimelike_to_int(data)  # type: ignore[arg-type]

to_native_dtype 

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.

Source code in zarr/core/dtype/npy/time.py 
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
def to_native_dtype(self) -> BaseTimeDType_co:
    # Numpy does not allow creating datetime64 or timedelta64 via
    # np.dtypes.{dtype_name}()
    # so we use np.dtype with a formatted string.
    """
    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_string = f"{self._numpy_name}[{self.scale_factor}{self.unit}]"
    return np.dtype(dtype_string).newbyteorder(endianness_to_numpy_str(self.endianness))  # type: ignore[return-value]

DateTime64JSON_V2

Bases: 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
}
Source code in zarr/core/dtype/npy/time.py 
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
class DateTime64JSON_V2(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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).


    Examples
    --------
    ```python
    {
        "name": "<M8[10s]",
        "object_codec_id": None
    }
    ```
    """

DateTime64JSON_V3

Bases: 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
        }
}
Source code in zarr/core/dtype/npy/time.py 
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
class DateTime64JSON_V3(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](https://zarr-specs.readthedocs.io/en/latest/spec/v3/datatypes.html#numpy-datetime64).

    Examples
    --------
    ```python
    {
        "name": "numpy.datetime64",
        "configuration": {
            "unit": "ms",
            "scale_factor": 1
            }
    }
    ```
    """

configuration instance-attribute 

configuration: ReadOnly[TConfig]

The configuration of the object.

name instance-attribute 

name: ReadOnly[TName]

The name of the object.

FixedLengthUTF32 dataclass

Bases: ZDType[StrDType[int], str_], HasEndianness, HasLength, 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_cls (Type[StrDType]) –

    The NumPy dtype class for this data type.

  • _zarr_v3_name (ClassVar[Literal['fixed_length_utf32']]) –

    The name of this data type in Zarr V3.

  • code_point_bytes (ClassVar[int] = 4) –

    The number of bytes per code point in UTF-32, which is 4.

Source code in zarr/core/dtype/npy/string.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
@dataclass(frozen=True, kw_only=True)
class FixedLengthUTF32(
    ZDType[np.dtypes.StrDType[int], np.str_], HasEndianness, HasLength, 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_cls : Type[np.dtypes.StrDType]
        The NumPy dtype class for this data type.
    _zarr_v3_name : ClassVar[Literal["fixed_length_utf32"]]
        The name of this data type in Zarr V3.
    code_point_bytes : ClassVar[int] = 4
        The number of bytes per code point in UTF-32, which is 4.
    """

    dtype_cls = np.dtypes.StrDType
    _zarr_v3_name: ClassVar[Literal["fixed_length_utf32"]] = "fixed_length_utf32"
    code_point_bytes: ClassVar[int] = 4  # utf32 is 4 bytes per code point

    def __post_init__(self) -> None:
        """
        We don't allow instances of this class with length less than 1 because there is no way such
        a data type can contain actual data.
        """
        if self.length < 1:
            raise ValueError(f"length must be >= 1, got {self.length}.")

    @classmethod
    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
        """
        Create a FixedLengthUTF32 from a NumPy data type.

        Parameters
        ----------
        dtype : TBaseDType
            The NumPy data type.

        Returns
        -------
        Self
            An instance of this data type.
        """
        if cls._check_native_dtype(dtype):
            endianness = get_endianness_from_numpy_dtype(dtype)
            return cls(
                length=dtype.itemsize // (cls.code_point_bytes),
                endianness=endianness,
            )
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    def to_native_dtype(self) -> np.dtypes.StrDType[int]:
        """
        Convert the FixedLengthUTF32 instance to a NumPy data type.

        Returns
        -------
        np.dtypes.StrDType[int]
            The NumPy data type.
        """
        byte_order = endianness_to_numpy_str(self.endianness)
        return self.dtype_cls(self.length).newbyteorder(byte_order)

    @classmethod
    def _check_json_v2(cls, data: DTypeJSON) -> TypeGuard[FixedLengthUTF32JSON_V2]:
        """
        Check that the input is a valid JSON representation of a NumPy U dtype.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        TypeGuard[FixedLengthUTF32JSON_V2]
            Whether the input is a valid JSON representation of a NumPy U dtype.
        """
        return (
            check_dtype_spec_v2(data)
            and isinstance(data["name"], str)
            and re.match(r"^[><]U\d+$", data["name"]) is not None
            and data["object_codec_id"] is None
        )

    @classmethod
    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[FixedLengthUTF32JSON_V3]:
        """
        Check that the input is a valid JSON representation of this class in Zarr V3.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        TypeGuard[FixedLengthUTF32JSONV3]
            Whether the input is a valid JSON representation of a NumPy U dtype.
        """
        return (
            isinstance(data, dict)
            and set(data.keys()) == {"name", "configuration"}
            and data["name"] == cls._zarr_v3_name
            and "configuration" in data
            and isinstance(data["configuration"], dict)
            and set(data["configuration"].keys()) == {"length_bytes"}
            and isinstance(data["configuration"]["length_bytes"], int)
        )

    @overload
    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[str, None]: ...

    @overload
    def to_json(self, zarr_format: Literal[3]) -> FixedLengthUTF32JSON_V3: ...

    def to_json(
        self, zarr_format: ZarrFormat
    ) -> DTypeConfig_V2[str, None] | FixedLengthUTF32JSON_V3:
        """
        Convert the FixedLengthUTF32 instance to a JSON representation.

        Parameters
        ----------
        zarr_format : ZarrFormat
            The Zarr format to use.

        Returns
        -------
        DTypeConfig_V2[str, None] | FixedLengthUTF32JSON_V3
            The JSON representation of the data type.
        """
        if zarr_format == 2:
            return {"name": self.to_native_dtype().str, "object_codec_id": None}
        elif zarr_format == 3:
            v3_unstable_dtype_warning(self)
            return {
                "name": self._zarr_v3_name,
                "configuration": {"length_bytes": self.length * self.code_point_bytes},
            }
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create a FixedLengthUTF32 from a JSON representation of a NumPy U dtype.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.
        """
        if cls._check_json_v2(data):
            # Construct the NumPy dtype instead of string parsing.
            name = data["name"]
            return cls.from_native_dtype(np.dtype(name))
        raise DataTypeValidationError(
            f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a string representation of a NumPy U dtype."
        )

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create a FixedLengthUTF32 from a JSON representation of a NumPy U dtype.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.
        """
        if cls._check_json_v3(data):
            return cls(length=data["configuration"]["length_bytes"] // cls.code_point_bytes)
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected {cls._zarr_v3_name}."
        raise DataTypeValidationError(msg)

    def default_scalar(self) -> np.str_:
        """
        Return the default scalar value for this data type.

        Returns
        -------
        ``np.str_``
            The default scalar value.
        """
        return np.str_("")

    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
        """
        Convert the scalar value to a JSON representation.

        Parameters
        ----------
        data : object
            The scalar value.
        zarr_format : ZarrFormat
            The Zarr format to use.

        Returns
        -------
        str
            The JSON representation of the scalar value.
        """
        return str(data)

    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.str_:
        """
        Convert the JSON representation of a scalar value to the native scalar value.

        Parameters
        ----------
        data : JSON
            The JSON data.
        zarr_format : ZarrFormat
            The Zarr format to use.

        Returns
        -------
        ``np.str_``
            The native scalar value.
        """
        if check_json_str(data):
            return self.to_native_dtype().type(data)
        raise TypeError(f"Invalid type: {data}. Expected a string.")  # pragma: no cover

    def _check_scalar(self, data: object) -> TypeGuard[SupportsStr]:
        """
        Check that the input is a valid scalar value for this data type.

        Parameters
        ----------
        data : object
            The scalar value.

        Returns
        -------
        TypeGuard[SupportsStr]
            Whether the input is a valid scalar value for this data type.
        """
        # this is generous for backwards compatibility
        return isinstance(data, SupportsStr)

    def cast_scalar(self, data: object) -> np.str_:
        """
        Cast the scalar value to the native scalar value.

        Parameters
        ----------
        data : object
            The scalar value.

        Returns
        -------
        ``np.str_``
            The native scalar value.
        """
        if self._check_scalar(data):
            # We explicitly truncate before casting because of the following NumPy behavior:
            # >>> x = np.dtype('U3').type('hello world')
            # >>> x
            # np.str_('hello world')
            # >>> x.dtype
            # dtype('U11')

            return self.to_native_dtype().type(str(data)[: self.length])

        msg = (  # pragma: no cover
            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
            f"data type {self}."
        )
        raise TypeError(msg)  # pragma: no-cover

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return self.length * self.code_point_bytes

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

__post_init__ 

__post_init__() -> None

We don't allow instances of this class with length less than 1 because there is no way such a data type can contain actual data.

Source code in zarr/core/dtype/npy/string.py 
131
132
133
134
135
136
137
def __post_init__(self) -> None:
    """
    We don't allow instances of this class with length less than 1 because there is no way such
    a data type can contain actual data.
    """
    if self.length < 1:
        raise ValueError(f"length must be >= 1, got {self.length}.")

cast_scalar 

cast_scalar(data: object) -> str_

Cast the scalar value to the native scalar value.

Parameters:

  • data (object) –

    The scalar value.

Returns:

  • ``np.str_`` –

    The native scalar value.

Source code in zarr/core/dtype/npy/string.py 
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
def cast_scalar(self, data: object) -> np.str_:
    """
    Cast the scalar value to the native scalar value.

    Parameters
    ----------
    data : object
        The scalar value.

    Returns
    -------
    ``np.str_``
        The native scalar value.
    """
    if self._check_scalar(data):
        # We explicitly truncate before casting because of the following NumPy behavior:
        # >>> x = np.dtype('U3').type('hello world')
        # >>> x
        # np.str_('hello world')
        # >>> x.dtype
        # dtype('U11')

        return self.to_native_dtype().type(str(data)[: self.length])

    msg = (  # pragma: no cover
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)  # pragma: no-cover

default_scalar 

default_scalar() -> str_

Return the default scalar value for this data type.

Returns:

  • ``np.str_`` –

    The default scalar value.

Source code in zarr/core/dtype/npy/string.py 
298
299
300
301
302
303
304
305
306
307
def default_scalar(self) -> np.str_:
    """
    Return the default scalar value for this data type.

    Returns
    -------
    ``np.str_``
        The default scalar value.
    """
    return np.str_("")

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> str_

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

Parameters:

  • data (JSON) –

    The JSON data.

  • zarr_format (ZarrFormat) –

    The Zarr format to use.

Returns:

  • ``np.str_`` –

    The native scalar value.

Source code in zarr/core/dtype/npy/string.py 
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.str_:
    """
    Convert the JSON representation of a scalar value to the native scalar value.

    Parameters
    ----------
    data : JSON
        The JSON data.
    zarr_format : ZarrFormat
        The Zarr format to use.

    Returns
    -------
    ``np.str_``
        The native scalar value.
    """
    if check_json_str(data):
        return self.to_native_dtype().type(data)
    raise TypeError(f"Invalid type: {data}. Expected a string.")  # pragma: no cover

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

Create a FixedLengthUTF32 from a NumPy data type.

Parameters:

  • dtype (TBaseDType) –

    The NumPy data type.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/npy/string.py 
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create a FixedLengthUTF32 from a NumPy data type.

    Parameters
    ----------
    dtype : TBaseDType
        The NumPy data type.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if cls._check_native_dtype(dtype):
        endianness = get_endianness_from_numpy_dtype(dtype)
        return cls(
            length=dtype.itemsize // (cls.code_point_bytes),
            endianness=endianness,
        )
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[str, None]

to_json(zarr_format: Literal[3]) -> FixedLengthUTF32JSON_V3

to_json(
    zarr_format: ZarrFormat,
) -> DTypeConfig_V2[str, None] | FixedLengthUTF32JSON_V3

Convert the FixedLengthUTF32 instance to a JSON representation.

Parameters:

  • zarr_format (ZarrFormat) –

    The Zarr format to use.

Returns:

Source code in zarr/core/dtype/npy/string.py 
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
def to_json(
    self, zarr_format: ZarrFormat
) -> DTypeConfig_V2[str, None] | FixedLengthUTF32JSON_V3:
    """
    Convert the FixedLengthUTF32 instance to a JSON representation.

    Parameters
    ----------
    zarr_format : ZarrFormat
        The Zarr format to use.

    Returns
    -------
    DTypeConfig_V2[str, None] | FixedLengthUTF32JSON_V3
        The JSON representation of the data type.
    """
    if zarr_format == 2:
        return {"name": self.to_native_dtype().str, "object_codec_id": None}
    elif zarr_format == 3:
        v3_unstable_dtype_warning(self)
        return {
            "name": self._zarr_v3_name,
            "configuration": {"length_bytes": self.length * self.code_point_bytes},
        }
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> str

Convert the scalar value to a JSON representation.

Parameters:

  • data (object) –

    The scalar value.

  • zarr_format (ZarrFormat) –

    The Zarr format to use.

Returns:

  • str –

    The JSON representation of the scalar value.

Source code in zarr/core/dtype/npy/string.py 
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
    """
    Convert the scalar value to a JSON representation.

    Parameters
    ----------
    data : object
        The scalar value.
    zarr_format : ZarrFormat
        The Zarr format to use.

    Returns
    -------
    str
        The JSON representation of the scalar value.
    """
    return str(data)

to_native_dtype 

to_native_dtype() -> StrDType[int]

Convert the FixedLengthUTF32 instance to a NumPy data type.

Returns:

  • StrDType[int] –

    The NumPy data type.

Source code in zarr/core/dtype/npy/string.py 
164
165
166
167
168
169
170
171
172
173
174
def to_native_dtype(self) -> np.dtypes.StrDType[int]:
    """
    Convert the FixedLengthUTF32 instance to a NumPy data type.

    Returns
    -------
    np.dtypes.StrDType[int]
        The NumPy data type.
    """
    byte_order = endianness_to_numpy_str(self.endianness)
    return self.dtype_cls(self.length).newbyteorder(byte_order)

FixedLengthUTF32JSON_V2

Bases: 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
}
Source code in zarr/core/dtype/npy/string.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
class FixedLengthUTF32JSON_V2(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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

    Examples
    --------

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

FixedLengthUTF32JSON_V3

Bases: 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
}
Source code in zarr/core/dtype/npy/string.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
class FixedLengthUTF32JSON_V3(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
    --------
    ```python
    {
        "name": "fixed_length_utf32",
        "configuration": {
            "length_bytes": 12
    }
    ```
    """

configuration instance-attribute 

configuration: ReadOnly[TConfig]

The configuration of the object.

name instance-attribute 

name: ReadOnly[TName]

The name of the object.

Float16 dataclass

Bases: BaseFloat[Float16DType, 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_cls (Type[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.

Source code in zarr/core/dtype/npy/float.py 
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
@dataclass(frozen=True, kw_only=True)
class Float16(BaseFloat[np.dtypes.Float16DType, np.float16]):
    """
    A Zarr data type for arrays containing 16-bit floating point numbers.

    Wraps the [`np.dtypes.Float16DType`][numpy.dtypes.Float16DType] data type. Scalars for this data type are instances
    of [`np.float16`][numpy.float16].

    Attributes
    ----------
    dtype_cls : Type[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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
    """

    dtype_cls = np.dtypes.Float16DType
    _zarr_v3_name = "float16"
    _zarr_v2_names: ClassVar[tuple[Literal[">f2"], Literal["<f2"]]] = (">f2", "<f2")

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 2

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> TFloatScalar_co

Cast a scalar value to a NumPy float scalar.

Parameters:

  • data (object) –

    The scalar value to cast.

Returns:

  • TFloatScalar_co –

    The NumPy float scalar.

Source code in zarr/core/dtype/npy/float.py 
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
def cast_scalar(self, data: object) -> TFloatScalar_co:
    """
    Cast a scalar value to a NumPy float scalar.

    Parameters
    ----------
    data : object
        The scalar value to cast.

    Returns
    -------
    TFloatScalar_co
        The NumPy float scalar.
    """
    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> TFloatScalar_co

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

Returns:

  • TFloatScalar_co –

    The default value.

Source code in zarr/core/dtype/npy/float.py 
243
244
245
246
247
248
249
250
251
252
def default_scalar(self) -> TFloatScalar_co:
    """
    Get the default value, which is 0 cast to this zdtype.

    Returns
    -------
    TFloatScalar_co
        The default value.
    """
    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TFloatScalar_co

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • TFloatScalar_co –

    The NumPy float scalar.

Source code in zarr/core/dtype/npy/float.py 
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TFloatScalar_co:
    """
    Read a JSON-serializable value as a NumPy float scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    TFloatScalar_co
        The NumPy float scalar.
    """
    if zarr_format == 2:
        if check_json_float_v2(data):
            return self._cast_scalar_unchecked(float_from_json_v2(data))
        else:
            raise TypeError(
                f"Invalid type: {data}. Expected a float or a special string encoding of a float."
            )
    elif zarr_format == 3:
        if check_json_float_v3(data):
            return self._cast_scalar_unchecked(float_from_json_v3(data))
        else:
            raise TypeError(
                f"Invalid type: {data}. Expected a float or a special string encoding of a float."
            )
    else:
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (TBaseDType) –

    The NumPy data type.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/npy/float.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an instance of this ZDType from a NumPy data type.

    Parameters
    ----------
    dtype : TBaseDType
        The NumPy data type.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if cls._check_native_dtype(dtype):
        return cls(endianness=get_endianness_from_numpy_dtype(dtype))
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[str, None]

to_json(zarr_format: Literal[3]) -> str

to_json(
    zarr_format: ZarrFormat,
) -> DTypeConfig_V2[str, None] | str

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

Parameters:

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • DTypeConfig_V2[str, None] or str –

    The JSON-serializable representation of the wrapped data type.

Raises:

Source code in zarr/core/dtype/npy/float.py 
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def to_json(self, zarr_format: ZarrFormat) -> DTypeConfig_V2[str, None] | str:
    """
    Convert the wrapped data type to a JSON-serializable form.

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        return {"name": self.to_native_dtype().str, "object_codec_id": None}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> float | str

Convert an object to a JSON-serializable float.

Parameters:

  • data (_BaseScalar) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/npy/float.py 
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> float | str:
    """
    Convert an object to a JSON-serializable float.

    Parameters
    ----------
    data : _BaseScalar
        The value to convert.
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        return float_to_json_v2(self.cast_scalar(data))
    elif zarr_format == 3:
        return float_to_json_v3(self.cast_scalar(data))
    else:
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_native_dtype 

to_native_dtype() -> TFloatDType_co

Convert the wrapped data type to a NumPy data type.

Returns:

  • TFloatDType_co –

    The NumPy data type.

Source code in zarr/core/dtype/npy/float.py 
65
66
67
68
69
70
71
72
73
74
75
def to_native_dtype(self) -> TFloatDType_co:
    """
    Convert the wrapped data type to a NumPy data type.

    Returns
    -------
    TFloatDType_co
        The NumPy data type.
    """
    byte_order = endianness_to_numpy_str(self.endianness)
    return self.dtype_cls().newbyteorder(byte_order)  # type: ignore[return-value]

Float32 dataclass

Bases: BaseFloat[Float32DType, 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_cls (Type[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.

Source code in zarr/core/dtype/npy/float.py 
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
@dataclass(frozen=True, kw_only=True)
class Float32(BaseFloat[np.dtypes.Float32DType, np.float32]):
    """
    A Zarr data type for arrays containing 32-bit floating point numbers.

    Wraps the [`np.dtypes.Float32DType`][numpy.dtypes.Float32DType] data type. Scalars for this data type are instances
    of [`np.float32`][numpy.float32].

    Attributes
    ----------
    dtype_cls : Type[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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
    """

    dtype_cls = np.dtypes.Float32DType
    _zarr_v3_name = "float32"
    _zarr_v2_names: ClassVar[tuple[Literal[">f4"], Literal["<f4"]]] = (">f4", "<f4")

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 4

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> TFloatScalar_co

Cast a scalar value to a NumPy float scalar.

Parameters:

  • data (object) –

    The scalar value to cast.

Returns:

  • TFloatScalar_co –

    The NumPy float scalar.

Source code in zarr/core/dtype/npy/float.py 
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
def cast_scalar(self, data: object) -> TFloatScalar_co:
    """
    Cast a scalar value to a NumPy float scalar.

    Parameters
    ----------
    data : object
        The scalar value to cast.

    Returns
    -------
    TFloatScalar_co
        The NumPy float scalar.
    """
    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> TFloatScalar_co

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

Returns:

  • TFloatScalar_co –

    The default value.

Source code in zarr/core/dtype/npy/float.py 
243
244
245
246
247
248
249
250
251
252
def default_scalar(self) -> TFloatScalar_co:
    """
    Get the default value, which is 0 cast to this zdtype.

    Returns
    -------
    TFloatScalar_co
        The default value.
    """
    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TFloatScalar_co

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • TFloatScalar_co –

    The NumPy float scalar.

Source code in zarr/core/dtype/npy/float.py 
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TFloatScalar_co:
    """
    Read a JSON-serializable value as a NumPy float scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    TFloatScalar_co
        The NumPy float scalar.
    """
    if zarr_format == 2:
        if check_json_float_v2(data):
            return self._cast_scalar_unchecked(float_from_json_v2(data))
        else:
            raise TypeError(
                f"Invalid type: {data}. Expected a float or a special string encoding of a float."
            )
    elif zarr_format == 3:
        if check_json_float_v3(data):
            return self._cast_scalar_unchecked(float_from_json_v3(data))
        else:
            raise TypeError(
                f"Invalid type: {data}. Expected a float or a special string encoding of a float."
            )
    else:
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (TBaseDType) –

    The NumPy data type.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/npy/float.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an instance of this ZDType from a NumPy data type.

    Parameters
    ----------
    dtype : TBaseDType
        The NumPy data type.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if cls._check_native_dtype(dtype):
        return cls(endianness=get_endianness_from_numpy_dtype(dtype))
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[str, None]

to_json(zarr_format: Literal[3]) -> str

to_json(
    zarr_format: ZarrFormat,
) -> DTypeConfig_V2[str, None] | str

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

Parameters:

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • DTypeConfig_V2[str, None] or str –

    The JSON-serializable representation of the wrapped data type.

Raises:

Source code in zarr/core/dtype/npy/float.py 
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def to_json(self, zarr_format: ZarrFormat) -> DTypeConfig_V2[str, None] | str:
    """
    Convert the wrapped data type to a JSON-serializable form.

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        return {"name": self.to_native_dtype().str, "object_codec_id": None}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> float | str

Convert an object to a JSON-serializable float.

Parameters:

  • data (_BaseScalar) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/npy/float.py 
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> float | str:
    """
    Convert an object to a JSON-serializable float.

    Parameters
    ----------
    data : _BaseScalar
        The value to convert.
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        return float_to_json_v2(self.cast_scalar(data))
    elif zarr_format == 3:
        return float_to_json_v3(self.cast_scalar(data))
    else:
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_native_dtype 

to_native_dtype() -> TFloatDType_co

Convert the wrapped data type to a NumPy data type.

Returns:

  • TFloatDType_co –

    The NumPy data type.

Source code in zarr/core/dtype/npy/float.py 
65
66
67
68
69
70
71
72
73
74
75
def to_native_dtype(self) -> TFloatDType_co:
    """
    Convert the wrapped data type to a NumPy data type.

    Returns
    -------
    TFloatDType_co
        The NumPy data type.
    """
    byte_order = endianness_to_numpy_str(self.endianness)
    return self.dtype_cls().newbyteorder(byte_order)  # type: ignore[return-value]

Float64 dataclass

Bases: BaseFloat[Float64DType, 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_cls (Type[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.

Source code in zarr/core/dtype/npy/float.py 
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
@dataclass(frozen=True, kw_only=True)
class Float64(BaseFloat[np.dtypes.Float64DType, np.float64]):
    """
    A Zarr data type for arrays containing 64-bit floating point numbers.

    Wraps the [`np.dtypes.Float64DType`][numpy.dtypes.Float64DType] data type. Scalars for this data type are instances
    of [`np.float64`][numpy.float64].

    Attributes
    ----------
    dtype_cls : Type[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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
    """

    dtype_cls = np.dtypes.Float64DType
    _zarr_v3_name = "float64"
    _zarr_v2_names: ClassVar[tuple[Literal[">f8"], Literal["<f8"]]] = (">f8", "<f8")

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 8

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> TFloatScalar_co

Cast a scalar value to a NumPy float scalar.

Parameters:

  • data (object) –

    The scalar value to cast.

Returns:

  • TFloatScalar_co –

    The NumPy float scalar.

Source code in zarr/core/dtype/npy/float.py 
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
def cast_scalar(self, data: object) -> TFloatScalar_co:
    """
    Cast a scalar value to a NumPy float scalar.

    Parameters
    ----------
    data : object
        The scalar value to cast.

    Returns
    -------
    TFloatScalar_co
        The NumPy float scalar.
    """
    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> TFloatScalar_co

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

Returns:

  • TFloatScalar_co –

    The default value.

Source code in zarr/core/dtype/npy/float.py 
243
244
245
246
247
248
249
250
251
252
def default_scalar(self) -> TFloatScalar_co:
    """
    Get the default value, which is 0 cast to this zdtype.

    Returns
    -------
    TFloatScalar_co
        The default value.
    """
    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TFloatScalar_co

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • TFloatScalar_co –

    The NumPy float scalar.

Source code in zarr/core/dtype/npy/float.py 
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TFloatScalar_co:
    """
    Read a JSON-serializable value as a NumPy float scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    TFloatScalar_co
        The NumPy float scalar.
    """
    if zarr_format == 2:
        if check_json_float_v2(data):
            return self._cast_scalar_unchecked(float_from_json_v2(data))
        else:
            raise TypeError(
                f"Invalid type: {data}. Expected a float or a special string encoding of a float."
            )
    elif zarr_format == 3:
        if check_json_float_v3(data):
            return self._cast_scalar_unchecked(float_from_json_v3(data))
        else:
            raise TypeError(
                f"Invalid type: {data}. Expected a float or a special string encoding of a float."
            )
    else:
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (TBaseDType) –

    The NumPy data type.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/npy/float.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an instance of this ZDType from a NumPy data type.

    Parameters
    ----------
    dtype : TBaseDType
        The NumPy data type.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if cls._check_native_dtype(dtype):
        return cls(endianness=get_endianness_from_numpy_dtype(dtype))
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[str, None]

to_json(zarr_format: Literal[3]) -> str

to_json(
    zarr_format: ZarrFormat,
) -> DTypeConfig_V2[str, None] | str

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

Parameters:

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • DTypeConfig_V2[str, None] or str –

    The JSON-serializable representation of the wrapped data type.

Raises:

Source code in zarr/core/dtype/npy/float.py 
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def to_json(self, zarr_format: ZarrFormat) -> DTypeConfig_V2[str, None] | str:
    """
    Convert the wrapped data type to a JSON-serializable form.

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        return {"name": self.to_native_dtype().str, "object_codec_id": None}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> float | str

Convert an object to a JSON-serializable float.

Parameters:

  • data (_BaseScalar) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/npy/float.py 
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> float | str:
    """
    Convert an object to a JSON-serializable float.

    Parameters
    ----------
    data : _BaseScalar
        The value to convert.
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        return float_to_json_v2(self.cast_scalar(data))
    elif zarr_format == 3:
        return float_to_json_v3(self.cast_scalar(data))
    else:
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_native_dtype 

to_native_dtype() -> TFloatDType_co

Convert the wrapped data type to a NumPy data type.

Returns:

  • TFloatDType_co –

    The NumPy data type.

Source code in zarr/core/dtype/npy/float.py 
65
66
67
68
69
70
71
72
73
74
75
def to_native_dtype(self) -> TFloatDType_co:
    """
    Convert the wrapped data type to a NumPy data type.

    Returns
    -------
    TFloatDType_co
        The NumPy data type.
    """
    byte_order = endianness_to_numpy_str(self.endianness)
    return self.dtype_cls().newbyteorder(byte_order)  # type: ignore[return-value]

Int16 dataclass

Bases: BaseInt[Int16DType, int16], 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_cls (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.

Source code in zarr/core/dtype/npy/int.py 
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
@dataclass(frozen=True, kw_only=True)
class Int16(BaseInt[np.dtypes.Int16DType, np.int16], HasEndianness):
    """
    A Zarr data type for arrays containing 16-bit signed integers.

    Wraps the [`np.dtypes.Int16DType`][numpy.dtypes.Int16DType] data type. Scalars for this data type are instances of
    [`np.int16`][numpy.int16].

    Attributes
    ----------
    dtype_cls : np.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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
    """

    dtype_cls = np.dtypes.Int16DType
    _zarr_v3_name: ClassVar[Literal["int16"]] = "int16"
    _zarr_v2_names: ClassVar[tuple[Literal[">i2"], Literal["<i2"]]] = (">i2", "<i2")

    @classmethod
    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
        """
        Create an instance of this data type from a np.dtype('int16') instance.

        Parameters
        ----------
        dtype : np.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').
        """
        if cls._check_native_dtype(dtype):
            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    def to_native_dtype(self) -> np.dtypes.Int16DType:
        """
        Convert the data type to a np.dtype('int16') instance.

        Returns
        -------
        np.dtype
            The np.dtype('int16') instance.
        """
        byte_order = endianness_to_numpy_str(self.endianness)
        return self.dtype_cls().newbyteorder(byte_order)

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from Zarr V2-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class.
        """
        if cls._check_json_v2(data):
            # Going via NumPy ensures that we get the endianness correct without
            # annoying string parsing.
            name = data["name"]
            return cls.from_native_dtype(np.dtype(name))
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected one of the strings {cls._zarr_v2_names!r}."
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from Zarr V3-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class.
        """
        if cls._check_json_v3(data):
            return cls()
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal[">i2", "<i2"], None]: ...

    @overload
    def to_json(self, zarr_format: Literal[3]) -> Literal["int16"]: ...

    def to_json(
        self, zarr_format: ZarrFormat
    ) -> DTypeConfig_V2[Literal[">i2", "<i2"], None] | Literal["int16"]:
        """
        Serialize this ZDType to v2- or v3-flavored JSON

        Parameters
        ----------
        zarr_format : ZarrFormat
            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.
        """
        if zarr_format == 2:
            name = self.to_native_dtype().str
            return {"name": name, "object_codec_id": None}
        elif zarr_format == 3:
            return self._zarr_v3_name
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 2

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> TIntScalar_co

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

Parameters:

  • data (object) –

    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.

Source code in zarr/core/dtype/npy/int.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def cast_scalar(self, data: object) -> TIntScalar_co:
    """
    Attempt to cast a given object to a NumPy integer scalar.

    Parameters
    ----------
    data : object
        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.
    """

    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> TIntScalar_co

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

Returns:

  • TIntScalar_co –

    The default value.

Source code in zarr/core/dtype/npy/int.py 
176
177
178
179
180
181
182
183
184
185
def default_scalar(self) -> TIntScalar_co:
    """
    Get the default value, which is 0 cast to this dtype.

    Returns
    -------
    TIntScalar_co
        The default value.
    """
    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TIntScalar_co

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • TIntScalar_co –

    The NumPy int scalar.

Raises:

  • TypeError –

    If the input is not a valid integer type.

Source code in zarr/core/dtype/npy/int.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TIntScalar_co:
    """
    Read a JSON-serializable value as a NumPy int scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    TIntScalar_co
        The NumPy int scalar.

    Raises
    ------
    TypeError
        If the input is not a valid integer type.
    """
    if check_json_int(data):
        return self._cast_scalar_unchecked(data)
    if check_json_intish_float(data):
        return self._cast_scalar_unchecked(int(data))
    raise TypeError(f"Invalid type: {data}. Expected an integer.")

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (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').

Source code in zarr/core/dtype/npy/int.py 
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an instance of this data type from a np.dtype('int16') instance.

    Parameters
    ----------
    dtype : np.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').
    """
    if cls._check_native_dtype(dtype):
        return cls(endianness=get_endianness_from_numpy_dtype(dtype))
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[Literal[">i2", "<i2"], None]

to_json(zarr_format: Literal[3]) -> Literal['int16']

to_json(
    zarr_format: ZarrFormat,
) -> (
    DTypeConfig_V2[Literal[">i2", "<i2"], None]
    | Literal["int16"]
)

Serialize this ZDType to v2- or v3-flavored JSON

Parameters:

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/npy/int.py 
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
def to_json(
    self, zarr_format: ZarrFormat
) -> DTypeConfig_V2[Literal[">i2", "<i2"], None] | Literal["int16"]:
    """
    Serialize this ZDType to v2- or v3-flavored JSON

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        name = self.to_native_dtype().str
        return {"name": name, "object_codec_id": None}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> int

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

Parameters:

  • data (object) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • int –

    The JSON-serializable form of the scalar.

Source code in zarr/core/dtype/npy/int.py 
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
    """
    Convert an object to a JSON serializable scalar. For the integer data types,
    the JSON form is a plain integer.

    Parameters
    ----------
    data : object
        The value to convert.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    int
        The JSON-serializable form of the scalar.
    """
    return int(self.cast_scalar(data))

to_native_dtype 

to_native_dtype() -> Int16DType

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

Returns:

  • dtype –

    The np.dtype('int16') instance.

Source code in zarr/core/dtype/npy/int.py 
587
588
589
590
591
592
593
594
595
596
597
def to_native_dtype(self) -> np.dtypes.Int16DType:
    """
    Convert the data type to a np.dtype('int16') instance.

    Returns
    -------
    np.dtype
        The np.dtype('int16') instance.
    """
    byte_order = endianness_to_numpy_str(self.endianness)
    return self.dtype_cls().newbyteorder(byte_order)

Int32 dataclass

Bases: BaseInt[Int32DType, int32], 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_cls (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.

Source code in zarr/core/dtype/npy/int.py 
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
@dataclass(frozen=True, kw_only=True)
class Int32(BaseInt[np.dtypes.Int32DType, np.int32], HasEndianness):
    """
    A Zarr data type for arrays containing 32-bit signed integers.

    Wraps the [`np.dtypes.Int32DType`][numpy.dtypes.Int32DType] data type. Scalars for this data type are instances of
    [`np.int32`][numpy.int32].

    Attributes
    ----------
    dtype_cls : np.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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
    """

    dtype_cls = np.dtypes.Int32DType
    _zarr_v3_name: ClassVar[Literal["int32"]] = "int32"
    _zarr_v2_names: ClassVar[tuple[Literal[">i4"], Literal["<i4"]]] = (">i4", "<i4")

    @classmethod
    def _check_native_dtype(cls: type[Self], dtype: TBaseDType) -> TypeGuard[np.dtypes.Int32DType]:
        """
        A type guard that checks if the input is assignable to the type of ``cls.dtype_class``

        This method is overridden for this particular data type because of a Windows-specific issue
        where np.dtype('i') creates an instance of ``np.dtypes.IntDType``, rather than an
        instance of ``np.dtypes.Int32DType``, even though both represent 32-bit signed integers.

        Parameters
        ----------
        dtype : TDType
            The dtype to check.

        Returns
        -------
        Bool
            True if the dtype matches, False otherwise.
        """
        return super()._check_native_dtype(dtype) or dtype == np.dtypes.Int32DType()

    @classmethod
    def from_native_dtype(cls: type[Self], dtype: TBaseDType) -> Self:
        """
        Create an Int32 from a np.dtype('int32') instance.

        Parameters
        ----------
        dtype : TBaseDType
            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.
        """
        if cls._check_native_dtype(dtype):
            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    def to_native_dtype(self: Self) -> np.dtypes.Int32DType:
        """
        Convert the Int32 instance to a np.dtype('int32') instance.

        Returns
        -------
        np.dtypes.Int32DType
            The np.dtype('int32') instance.
        """
        byte_order = endianness_to_numpy_str(self.endianness)
        return self.dtype_cls().newbyteorder(byte_order)

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create an Int32 from Zarr V2-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class Int32.
        """
        if cls._check_json_v2(data):
            # Going via NumPy ensures that we get the endianness correct without
            # annoying string parsing.
            name = data["name"]
            return cls.from_native_dtype(np.dtype(name))
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected one of the strings {cls._zarr_v2_names!r}."
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create an Int32 from Zarr V3-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class Int32.
        """
        if cls._check_json_v3(data):
            return cls()
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal[">i4", "<i4"], None]: ...

    @overload
    def to_json(self, zarr_format: Literal[3]) -> Literal["int32"]: ...

    def to_json(
        self, zarr_format: ZarrFormat
    ) -> DTypeConfig_V2[Literal[">i4", "<i4"], None] | Literal["int32"]:
        """
        Serialize this ZDType to v2- or v3-flavored JSON

        Parameters
        ----------
        zarr_format : ZarrFormat
            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.
        """
        if zarr_format == 2:
            name = self.to_native_dtype().str
            return {"name": name, "object_codec_id": None}
        elif zarr_format == 3:
            return self._zarr_v3_name
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 4

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> TIntScalar_co

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

Parameters:

  • data (object) –

    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.

Source code in zarr/core/dtype/npy/int.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def cast_scalar(self, data: object) -> TIntScalar_co:
    """
    Attempt to cast a given object to a NumPy integer scalar.

    Parameters
    ----------
    data : object
        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.
    """

    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> TIntScalar_co

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

Returns:

  • TIntScalar_co –

    The default value.

Source code in zarr/core/dtype/npy/int.py 
176
177
178
179
180
181
182
183
184
185
def default_scalar(self) -> TIntScalar_co:
    """
    Get the default value, which is 0 cast to this dtype.

    Returns
    -------
    TIntScalar_co
        The default value.
    """
    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TIntScalar_co

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • TIntScalar_co –

    The NumPy int scalar.

Raises:

  • TypeError –

    If the input is not a valid integer type.

Source code in zarr/core/dtype/npy/int.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TIntScalar_co:
    """
    Read a JSON-serializable value as a NumPy int scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    TIntScalar_co
        The NumPy int scalar.

    Raises
    ------
    TypeError
        If the input is not a valid integer type.
    """
    if check_json_int(data):
        return self._cast_scalar_unchecked(data)
    if check_json_intish_float(data):
        return self._cast_scalar_unchecked(int(data))
    raise TypeError(f"Invalid type: {data}. Expected an integer.")

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (TBaseDType) –

    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.

Source code in zarr/core/dtype/npy/int.py 
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
@classmethod
def from_native_dtype(cls: type[Self], dtype: TBaseDType) -> Self:
    """
    Create an Int32 from a np.dtype('int32') instance.

    Parameters
    ----------
    dtype : TBaseDType
        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.
    """
    if cls._check_native_dtype(dtype):
        return cls(endianness=get_endianness_from_numpy_dtype(dtype))
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[Literal[">i4", "<i4"], None]

to_json(zarr_format: Literal[3]) -> Literal['int32']

to_json(
    zarr_format: ZarrFormat,
) -> (
    DTypeConfig_V2[Literal[">i4", "<i4"], None]
    | Literal["int32"]
)

Serialize this ZDType to v2- or v3-flavored JSON

Parameters:

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/npy/int.py 
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
def to_json(
    self, zarr_format: ZarrFormat
) -> DTypeConfig_V2[Literal[">i4", "<i4"], None] | Literal["int32"]:
    """
    Serialize this ZDType to v2- or v3-flavored JSON

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        name = self.to_native_dtype().str
        return {"name": name, "object_codec_id": None}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> int

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

Parameters:

  • data (object) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • int –

    The JSON-serializable form of the scalar.

Source code in zarr/core/dtype/npy/int.py 
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
    """
    Convert an object to a JSON serializable scalar. For the integer data types,
    the JSON form is a plain integer.

    Parameters
    ----------
    data : object
        The value to convert.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    int
        The JSON-serializable form of the scalar.
    """
    return int(self.cast_scalar(data))

to_native_dtype 

to_native_dtype() -> Int32DType

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

Returns:

Source code in zarr/core/dtype/npy/int.py 
932
933
934
935
936
937
938
939
940
941
942
def to_native_dtype(self: Self) -> np.dtypes.Int32DType:
    """
    Convert the Int32 instance to a np.dtype('int32') instance.

    Returns
    -------
    np.dtypes.Int32DType
        The np.dtype('int32') instance.
    """
    byte_order = endianness_to_numpy_str(self.endianness)
    return self.dtype_cls().newbyteorder(byte_order)

Int64 dataclass

Bases: BaseInt[Int64DType, int64], 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_cls (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.

Source code in zarr/core/dtype/npy/int.py 
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
@dataclass(frozen=True, kw_only=True)
class Int64(BaseInt[np.dtypes.Int64DType, np.int64], HasEndianness):
    """
    A Zarr data type for arrays containing 64-bit signed integers.

    Wraps the [`np.dtypes.Int64DType`][numpy.dtypes.Int64DType] data type. Scalars for this data type are instances of
    [`np.int64`][numpy.int64].

    Attributes
    ----------
    dtype_cls : np.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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
    """

    dtype_cls = np.dtypes.Int64DType
    _zarr_v3_name: ClassVar[Literal["int64"]] = "int64"
    _zarr_v2_names: ClassVar[tuple[Literal[">i8"], Literal["<i8"]]] = (">i8", "<i8")

    @classmethod
    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
        """
        Create an Int64 from a np.dtype('int64') instance.

        Parameters
        ----------
        dtype : TBaseDType
            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.
        """
        if cls._check_native_dtype(dtype):
            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    def to_native_dtype(self) -> np.dtypes.Int64DType:
        """
        Create a NumPy signed 64-bit integer dtype instance from this Int64 ZDType.

        Returns
        -------
        np.dtypes.Int64DType
            The NumPy signed 64-bit integer dtype.
        """
        byte_order = endianness_to_numpy_str(self.endianness)
        return self.dtype_cls().newbyteorder(byte_order)

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from Zarr V2-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class 64-bit signed
            integer.
        """
        if cls._check_json_v2(data):
            # Going via NumPy ensures that we get the endianness correct without
            # annoying string parsing.
            name = data["name"]
            return cls.from_native_dtype(np.dtype(name))
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected one of the strings {cls._zarr_v2_names}."
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from Zarr V3-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class 64-bit signed
            integer.
        """
        if cls._check_json_v3(data):
            return cls()
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal[">i8", "<i8"], None]: ...
    @overload
    def to_json(self, zarr_format: Literal[3]) -> Literal["int64"]: ...
    def to_json(
        self, zarr_format: ZarrFormat
    ) -> DTypeConfig_V2[Literal[">i8", "<i8"], None] | Literal["int64"]:
        """
        Convert the data type to a JSON-serializable form.

        Parameters
        ----------
        zarr_format : ZarrFormat
            The Zarr format version.

        Returns
        -------
        DTypeConfig_V2[Literal[">i8", "<i8"], None] | Literal["int64"]
            The JSON-serializable representation of the data type.
        """
        if zarr_format == 2:
            name = self.to_native_dtype().str
            return {"name": name, "object_codec_id": None}
        elif zarr_format == 3:
            return self._zarr_v3_name
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 8

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> TIntScalar_co

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

Parameters:

  • data (object) –

    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.

Source code in zarr/core/dtype/npy/int.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def cast_scalar(self, data: object) -> TIntScalar_co:
    """
    Attempt to cast a given object to a NumPy integer scalar.

    Parameters
    ----------
    data : object
        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.
    """

    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> TIntScalar_co

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

Returns:

  • TIntScalar_co –

    The default value.

Source code in zarr/core/dtype/npy/int.py 
176
177
178
179
180
181
182
183
184
185
def default_scalar(self) -> TIntScalar_co:
    """
    Get the default value, which is 0 cast to this dtype.

    Returns
    -------
    TIntScalar_co
        The default value.
    """
    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TIntScalar_co

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • TIntScalar_co –

    The NumPy int scalar.

Raises:

  • TypeError –

    If the input is not a valid integer type.

Source code in zarr/core/dtype/npy/int.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TIntScalar_co:
    """
    Read a JSON-serializable value as a NumPy int scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    TIntScalar_co
        The NumPy int scalar.

    Raises
    ------
    TypeError
        If the input is not a valid integer type.
    """
    if check_json_int(data):
        return self._cast_scalar_unchecked(data)
    if check_json_intish_float(data):
        return self._cast_scalar_unchecked(int(data))
    raise TypeError(f"Invalid type: {data}. Expected an integer.")

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (TBaseDType) –

    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.

Source code in zarr/core/dtype/npy/int.py 
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an Int64 from a np.dtype('int64') instance.

    Parameters
    ----------
    dtype : TBaseDType
        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.
    """
    if cls._check_native_dtype(dtype):
        return cls(endianness=get_endianness_from_numpy_dtype(dtype))
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[Literal[">i8", "<i8"], None]

to_json(zarr_format: Literal[3]) -> Literal['int64']

to_json(
    zarr_format: ZarrFormat,
) -> (
    DTypeConfig_V2[Literal[">i8", "<i8"], None]
    | Literal["int64"]
)

Convert the data type to a JSON-serializable form.

Parameters:

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • DTypeConfig_V2[Literal['>i8', '<i8'], None] | Literal['int64'] –

    The JSON-serializable representation of the data type.

Source code in zarr/core/dtype/npy/int.py 
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
def to_json(
    self, zarr_format: ZarrFormat
) -> DTypeConfig_V2[Literal[">i8", "<i8"], None] | Literal["int64"]:
    """
    Convert the data type to a JSON-serializable form.

    Parameters
    ----------
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    DTypeConfig_V2[Literal[">i8", "<i8"], None] | Literal["int64"]
        The JSON-serializable representation of the data type.
    """
    if zarr_format == 2:
        name = self.to_native_dtype().str
        return {"name": name, "object_codec_id": None}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> int

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

Parameters:

  • data (object) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • int –

    The JSON-serializable form of the scalar.

Source code in zarr/core/dtype/npy/int.py 
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
    """
    Convert an object to a JSON serializable scalar. For the integer data types,
    the JSON form is a plain integer.

    Parameters
    ----------
    data : object
        The value to convert.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    int
        The JSON-serializable form of the scalar.
    """
    return int(self.cast_scalar(data))

to_native_dtype 

to_native_dtype() -> Int64DType

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

Returns:

  • Int64DType –

    The NumPy signed 64-bit integer dtype.

Source code in zarr/core/dtype/npy/int.py 
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
def to_native_dtype(self) -> np.dtypes.Int64DType:
    """
    Create a NumPy signed 64-bit integer dtype instance from this Int64 ZDType.

    Returns
    -------
    np.dtypes.Int64DType
        The NumPy signed 64-bit integer dtype.
    """
    byte_order = endianness_to_numpy_str(self.endianness)
    return self.dtype_cls().newbyteorder(byte_order)

Int8 dataclass

Bases: BaseInt[Int8DType, 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_cls (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.

Source code in zarr/core/dtype/npy/int.py 
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
@dataclass(frozen=True, kw_only=True)
class Int8(BaseInt[np.dtypes.Int8DType, np.int8]):
    """
    A Zarr data type for arrays containing 8-bit signed integers.

    Wraps the [`np.dtypes.Int8DType`][numpy.dtypes.Int8DType] data type. Scalars for this data type are
    instances of [`np.int8`][numpy.int8].

    Attributes
    ----------
    dtype_cls : np.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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
    """

    dtype_cls = np.dtypes.Int8DType
    _zarr_v3_name: ClassVar[Literal["int8"]] = "int8"
    _zarr_v2_names: ClassVar[tuple[Literal["|i1"]]] = ("|i1",)

    @classmethod
    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
        """
        Create an Int8 from a np.dtype('int8') instance.

        Parameters
        ----------
        dtype : TBaseDType
            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.
        """
        if cls._check_native_dtype(dtype):
            return cls()
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    def to_native_dtype(self: Self) -> np.dtypes.Int8DType:
        """
        Convert the Int8 instance to a np.dtype('int8') instance.

        Returns
        -------
        np.dtypes.Int8DType
            The np.dtype('int8') instance.
        """
        return self.dtype_cls()

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create an Int8 from Zarr V2-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class Int8.
        """
        if cls._check_json_v2(data):
            return cls()
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v2_names[0]!r}"
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create an Int8 from Zarr V3-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class Int8.
        """
        if cls._check_json_v3(data):
            return cls()
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal["|i1"], None]: ...

    @overload
    def to_json(self, zarr_format: Literal[3]) -> Literal["int8"]: ...

    def to_json(
        self, zarr_format: ZarrFormat
    ) -> DTypeConfig_V2[Literal["|i1"], None] | Literal["int8"]:
        """
        Convert the data type to a JSON-serializable form.

        Parameters
        ----------
        zarr_format : ZarrFormat
            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.
        """
        if zarr_format == 2:
            return {"name": self._zarr_v2_names[0], "object_codec_id": None}
        elif zarr_format == 3:
            return self._zarr_v3_name
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 1

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> TIntScalar_co

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

Parameters:

  • data (object) –

    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.

Source code in zarr/core/dtype/npy/int.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def cast_scalar(self, data: object) -> TIntScalar_co:
    """
    Attempt to cast a given object to a NumPy integer scalar.

    Parameters
    ----------
    data : object
        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.
    """

    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> TIntScalar_co

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

Returns:

  • TIntScalar_co –

    The default value.

Source code in zarr/core/dtype/npy/int.py 
176
177
178
179
180
181
182
183
184
185
def default_scalar(self) -> TIntScalar_co:
    """
    Get the default value, which is 0 cast to this dtype.

    Returns
    -------
    TIntScalar_co
        The default value.
    """
    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TIntScalar_co

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • TIntScalar_co –

    The NumPy int scalar.

Raises:

  • TypeError –

    If the input is not a valid integer type.

Source code in zarr/core/dtype/npy/int.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TIntScalar_co:
    """
    Read a JSON-serializable value as a NumPy int scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    TIntScalar_co
        The NumPy int scalar.

    Raises
    ------
    TypeError
        If the input is not a valid integer type.
    """
    if check_json_int(data):
        return self._cast_scalar_unchecked(data)
    if check_json_intish_float(data):
        return self._cast_scalar_unchecked(int(data))
    raise TypeError(f"Invalid type: {data}. Expected an integer.")

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (TBaseDType) –

    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.

Source code in zarr/core/dtype/npy/int.py 
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an Int8 from a np.dtype('int8') instance.

    Parameters
    ----------
    dtype : TBaseDType
        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.
    """
    if cls._check_native_dtype(dtype):
        return cls()
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[Literal["|i1"], None]

to_json(zarr_format: Literal[3]) -> Literal['int8']

to_json(
    zarr_format: ZarrFormat,
) -> DTypeConfig_V2[Literal["|i1"], None] | Literal["int8"]

Convert the data type to a JSON-serializable form.

Parameters:

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/npy/int.py 
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
def to_json(
    self, zarr_format: ZarrFormat
) -> DTypeConfig_V2[Literal["|i1"], None] | Literal["int8"]:
    """
    Convert the data type to a JSON-serializable form.

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        return {"name": self._zarr_v2_names[0], "object_codec_id": None}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> int

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

Parameters:

  • data (object) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • int –

    The JSON-serializable form of the scalar.

Source code in zarr/core/dtype/npy/int.py 
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
    """
    Convert an object to a JSON serializable scalar. For the integer data types,
    the JSON form is a plain integer.

    Parameters
    ----------
    data : object
        The value to convert.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    int
        The JSON-serializable form of the scalar.
    """
    return int(self.cast_scalar(data))

to_native_dtype 

to_native_dtype() -> Int8DType

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

Returns:

  • Int8DType –

    The np.dtype('int8') instance.

Source code in zarr/core/dtype/npy/int.py 
284
285
286
287
288
289
290
291
292
293
def to_native_dtype(self: Self) -> np.dtypes.Int8DType:
    """
    Convert the Int8 instance to a np.dtype('int8') instance.

    Returns
    -------
    np.dtypes.Int8DType
        The np.dtype('int8') instance.
    """
    return self.dtype_cls()

NullTerminatedBytes dataclass

Bases: ZDType[BytesDType[int], bytes_], HasLength, 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_name (ClassVar[Literal['null_terminated_bytes']]) –
  • length (int) –

    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.

Source code in zarr/core/dtype/npy/bytes.py 
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
@dataclass(frozen=True, kw_only=True)
class NullTerminatedBytes(ZDType[np.dtypes.BytesDType[int], np.bytes_], HasLength, HasItemSize):
    """
    A Zarr data type for arrays containing fixed-length null-terminated byte sequences.

    Wraps the [`np.dtypes.BytesDType`][numpy.dtypes.BytesDType] data type. Scalars for this data type are instances of
    [`np.bytes_`][numpy.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_name : ClassVar[Literal["null_terminated_bytes"]]
    length : int
        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.
    """

    dtype_cls = np.dtypes.BytesDType
    _zarr_v3_name: ClassVar[Literal["null_terminated_bytes"]] = "null_terminated_bytes"

    def __post_init__(self) -> None:
        """
        We don't allow instances of this class with length less than 1 because there is no way such
        a data type can contain actual data.
        """
        if self.length < 1:
            raise ValueError(f"length must be >= 1, got {self.length}.")

    @classmethod
    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
        """
        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
        ----------
        dtype : TBaseDType
            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.
        """

        if cls._check_native_dtype(dtype):
            return cls(length=dtype.itemsize)
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    def to_native_dtype(self) -> np.dtypes.BytesDType[int]:
        """
        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.
        """

        return self.dtype_cls(self.length)

    @classmethod
    def _check_json_v2(cls, data: DTypeJSON) -> TypeGuard[NullterminatedBytesJSON_V2]:
        """
        Check that the input is a valid JSON representation of NullTerminatedBytes in Zarr V2.

        The input data must be a mapping that contains a "name" key that matches the pattern
        "|S<number>" and an "object_codec_id" key that is None.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to check.

        Returns
        -------
        bool
            True if the input data is a valid representation, False otherwise.
        """

        return (
            check_dtype_spec_v2(data)
            and isinstance(data["name"], str)
            and re.match(r"^\|S\d+$", data["name"]) is not None
            and data["object_codec_id"] is None
        )

    @classmethod
    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[NullTerminatedBytesJSON_V3]:
        """
        Check that the input is a valid JSON representation of this class in Zarr V3.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to check.

        Returns
        -------
        TypeGuard[NullTerminatedBytesJSON_V3]
            True if the input is a valid representation of this class in Zarr V3, False
            otherwise.
        """
        return (
            isinstance(data, dict)
            and set(data.keys()) == {"name", "configuration"}
            and data["name"] == cls._zarr_v3_name
            and isinstance(data["configuration"], dict)
            and "length_bytes" in data["configuration"]
            and isinstance(data["configuration"]["length_bytes"], int)
        )

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this class from Zarr V2-flavored JSON.

        This method checks if the input data is a valid representation of
        this class in Zarr V2. If so, it returns a new instance of
        this class with a ``length`` as specified in the input data.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to parse.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input data is not a valid representation of this class.
        """

        if cls._check_json_v2(data):
            name = data["name"]
            return cls(length=int(name[2:]))
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a string like '|S1', '|S2', etc"
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this class from Zarr V3-flavored JSON.

        This method checks if the input data is a valid representation of
        this class in Zarr V3. If so, it returns a new instance of
        this class with a ``length`` as specified in the input data.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to parse.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input data is not a valid representation of this class.
        """
        if cls._check_json_v3(data):
            return cls(length=data["configuration"]["length_bytes"])
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> NullterminatedBytesJSON_V2: ...

    @overload
    def to_json(self, zarr_format: Literal[3]) -> NullTerminatedBytesJSON_V3: ...

    def to_json(
        self, zarr_format: ZarrFormat
    ) -> DTypeConfig_V2[str, None] | NullTerminatedBytesJSON_V3:
        """
        Generate a JSON representation of this data type.

        Parameters
        ----------
        zarr_format : ZarrFormat
            The zarr format version.

        Returns
        -------
        NullterminatedBytesJSON_V2 | NullTerminatedBytesJSON_V3
            The JSON-serializable representation of the data type
        """
        if zarr_format == 2:
            return {"name": self.to_native_dtype().str, "object_codec_id": None}
        elif zarr_format == 3:
            v3_unstable_dtype_warning(self)
            return {
                "name": self._zarr_v3_name,
                "configuration": {"length_bytes": self.length},
            }
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    def _check_scalar(self, data: object) -> TypeGuard[BytesLike]:
        """
        Check if the provided data is of type BytesLike.

        This method is used to verify if the input data can be considered as a
        scalar of bytes-like type, which includes NumPy bytes, strings, bytes,
        and integers.

        Parameters
        ----------
        data : object
            The data to check.

        Returns
        -------
        TypeGuard[BytesLike]
            True if the data is bytes-like, False otherwise.
        """

        return isinstance(data, BytesLike)

    def _cast_scalar_unchecked(self, data: BytesLike) -> np.bytes_:
        """
        Cast the provided scalar data to [`np.bytes_`][numpy.bytes_], truncating if necessary.

        Parameters
        ----------
        data : BytesLike
            The data to cast.

        Returns
        -------
        bytes : [`np.bytes_`][numpy.bytes_]
            The casted data as a NumPy bytes scalar.

        Notes
        -----
        This method does not perform any type checking.
        The input data must be bytes-like.
        """
        if isinstance(data, int):
            return self.to_native_dtype().type(str(data)[: self.length])
        else:
            return self.to_native_dtype().type(data[: self.length])

    def cast_scalar(self, data: object) -> np.bytes_:
        """
        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
        ----------
        data : object
            The data to be cast to a NumPy bytes scalar.

        Returns
        -------
        bytes : [`np.bytes_`][numpy.bytes_]
            The data cast as a NumPy bytes scalar.

        Raises
        ------
        TypeError
            If the data cannot be converted to a NumPy bytes scalar.
        """

        if self._check_scalar(data):
            return self._cast_scalar_unchecked(data)
        msg = (
            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
            f"data type {self}."
        )
        raise TypeError(msg)

    def default_scalar(self) -> np.bytes_:
        """
        Return a default scalar value, which for this data type is an empty byte string.

        Returns
        -------
        bytes : [`np.bytes_`][numpy.bytes_]
            The default scalar value.
        """
        return np.bytes_(b"")

    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
        """
        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
        ----------
        data : object
            The scalar to convert.
        zarr_format : ZarrFormat
            The zarr format version.

        Returns
        -------
        str
            A string representation of the scalar.
        """
        as_bytes = self.cast_scalar(data)
        return base64.standard_b64encode(as_bytes).decode("ascii")

    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.bytes_:
        """
        Read a JSON-serializable value as [`np.bytes_`][numpy.bytes_].

        Parameters
        ----------
        data : JSON
            The JSON-serializable base64-encoded string.
        zarr_format : ZarrFormat
            The zarr format version.

        Returns
        -------
        bytes : [`np.bytes_`][numpy.bytes_]
            The NumPy bytes scalar obtained from decoding the base64 string.

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

        if check_json_str(data):
            return self.to_native_dtype().type(base64.standard_b64decode(data.encode("ascii")))
        raise TypeError(
            f"Invalid type: {data}. Expected a base64-encoded string."
        )  # pragma: no cover

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return self.length

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

__post_init__ 

__post_init__() -> None

We don't allow instances of this class with length less than 1 because there is no way such a data type can contain actual data.

Source code in zarr/core/dtype/npy/bytes.py 
199
200
201
202
203
204
205
def __post_init__(self) -> None:
    """
    We don't allow instances of this class with length less than 1 because there is no way such
    a data type can contain actual data.
    """
    if self.length < 1:
        raise ValueError(f"length must be >= 1, got {self.length}.")

cast_scalar 

cast_scalar(data: object) -> bytes_

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:

  • data (object) –

    The data to be cast to a NumPy bytes scalar.

Returns:

  • bytes ( [`np.bytes_`][numpy.bytes_] ) –

    The data cast as a NumPy bytes scalar.

Raises:

  • TypeError –

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

Source code in zarr/core/dtype/npy/bytes.py 
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
def cast_scalar(self, data: object) -> np.bytes_:
    """
    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
    ----------
    data : object
        The data to be cast to a NumPy bytes scalar.

    Returns
    -------
    bytes : [`np.bytes_`][numpy.bytes_]
        The data cast as a NumPy bytes scalar.

    Raises
    ------
    TypeError
        If the data cannot be converted to a NumPy bytes scalar.
    """

    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> bytes_

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

Returns:

  • bytes ( [`np.bytes_`][numpy.bytes_] ) –

    The default scalar value.

Source code in zarr/core/dtype/npy/bytes.py 
470
471
472
473
474
475
476
477
478
479
def default_scalar(self) -> np.bytes_:
    """
    Return a default scalar value, which for this data type is an empty byte string.

    Returns
    -------
    bytes : [`np.bytes_`][numpy.bytes_]
        The default scalar value.
    """
    return np.bytes_(b"")

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> bytes_

Read a JSON-serializable value as np.bytes_.

Parameters:

  • data (JSON) –

    The JSON-serializable base64-encoded string.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • bytes ( [`np.bytes_`][numpy.bytes_] ) –

    The NumPy bytes scalar obtained from decoding the base64 string.

Raises:

  • TypeError –

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

Source code in zarr/core/dtype/npy/bytes.py 
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.bytes_:
    """
    Read a JSON-serializable value as [`np.bytes_`][numpy.bytes_].

    Parameters
    ----------
    data : JSON
        The JSON-serializable base64-encoded string.
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    bytes : [`np.bytes_`][numpy.bytes_]
        The NumPy bytes scalar obtained from decoding the base64 string.

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

    if check_json_str(data):
        return self.to_native_dtype().type(base64.standard_b64decode(data.encode("ascii")))
    raise TypeError(
        f"Invalid type: {data}. Expected a base64-encoded string."
    )  # pragma: no cover

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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:

  • dtype (TBaseDType) –

    The native dtype to convert.

Returns:

Raises:

  • DataTypeValidationError –

    If the dtype is not compatible with NullTerminatedBytes.

Source code in zarr/core/dtype/npy/bytes.py 
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    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
    ----------
    dtype : TBaseDType
        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.
    """

    if cls._check_native_dtype(dtype):
        return cls(length=dtype.itemsize)
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> NullterminatedBytesJSON_V2

to_json(
    zarr_format: Literal[3],
) -> NullTerminatedBytesJSON_V3

to_json(
    zarr_format: ZarrFormat,
) -> DTypeConfig_V2[str, None] | NullTerminatedBytesJSON_V3

Generate a JSON representation of this data type.

Parameters:

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

Source code in zarr/core/dtype/npy/bytes.py 
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
def to_json(
    self, zarr_format: ZarrFormat
) -> DTypeConfig_V2[str, None] | NullTerminatedBytesJSON_V3:
    """
    Generate a JSON representation of this data type.

    Parameters
    ----------
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    NullterminatedBytesJSON_V2 | NullTerminatedBytesJSON_V3
        The JSON-serializable representation of the data type
    """
    if zarr_format == 2:
        return {"name": self.to_native_dtype().str, "object_codec_id": None}
    elif zarr_format == 3:
        v3_unstable_dtype_warning(self)
        return {
            "name": self._zarr_v3_name,
            "configuration": {"length_bytes": self.length},
        }
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> str

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:

  • data (object) –

    The scalar to convert.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • str –

    A string representation of the scalar.

Source code in zarr/core/dtype/npy/bytes.py 
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
    """
    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
    ----------
    data : object
        The scalar to convert.
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    str
        A string representation of the scalar.
    """
    as_bytes = self.cast_scalar(data)
    return base64.standard_b64encode(as_bytes).decode("ascii")

to_native_dtype 

to_native_dtype() -> BytesDType[int]

Create a NumPy bytes dtype from this NullTerminatedBytes ZDType.

Returns:

  • BytesDType[int] –

    A NumPy data type object representing null-terminated bytes with a specified length.

Source code in zarr/core/dtype/npy/bytes.py 
238
239
240
241
242
243
244
245
246
247
248
def to_native_dtype(self) -> np.dtypes.BytesDType[int]:
    """
    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.
    """

    return self.dtype_cls(self.length)

NullTerminatedBytesJSON_V3

Bases: 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
    }
}
Source code in zarr/core/dtype/npy/bytes.py 
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
class NullTerminatedBytesJSON_V3(
    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
    --------
    ```python
    {
        "name": "null_terminated_bytes",
        "configuration": {
            "length_bytes": 12
        }
    }
    ```

    """

configuration instance-attribute 

configuration: ReadOnly[TConfig]

The configuration of the object.

name instance-attribute 

name: ReadOnly[TName]

The name of the object.

NullterminatedBytesJSON_V2

Bases: 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
}
Source code in zarr/core/dtype/npy/bytes.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
class NullterminatedBytesJSON_V2(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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).


    Examples
    --------
    ```python
    {
        "name": "|S10",
        "object_codec_id": None
    }
    ```
    """

RawBytes dataclass

Bases: ZDType[VoidDType[int], void], HasLength, 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_name (ClassVar[Literal['raw_bytes']]) –
  • length (int) –

    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.

Source code in zarr/core/dtype/npy/bytes.py 
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
@dataclass(frozen=True, kw_only=True)
class RawBytes(ZDType[np.dtypes.VoidDType[int], np.void], HasLength, 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`][numpy.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_name : ClassVar[Literal["raw_bytes"]]
    length : int
        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.

    """

    # np.dtypes.VoidDType is specified in an odd way in NumPy
    # it cannot be used to create instances of the dtype
    # so we have to tell mypy to ignore this here
    dtype_cls = np.dtypes.VoidDType  # type: ignore[assignment]
    _zarr_v3_name: ClassVar[Literal["raw_bytes"]] = "raw_bytes"

    def __post_init__(self) -> None:
        """
        We don't allow instances of this class with length less than 1 because there is no way such
        a data type can contain actual data.
        """
        if self.length < 1:
            raise ValueError(f"length must be >= 1, got {self.length}.")

    @classmethod
    def _check_native_dtype(
        cls: type[Self], dtype: TBaseDType
    ) -> TypeGuard[np.dtypes.VoidDType[int]]:
        """
        Check that the input is a NumPy void dtype with no fields.


        Numpy void dtype comes in two forms:
        * If the ``fields`` attribute is ``None``, then the dtype represents N raw bytes.
        * If the ``fields`` attribute is not ``None``, then the dtype represents a structured dtype,

        In this check we ensure that ``fields`` is ``None``.

        Parameters
        ----------
        dtype : TDBaseDType
            The dtype to check.

        Returns
        -------
        Bool
            True if the dtype is an instance of np.dtypes.VoidDType with no fields, False otherwise.
        """
        return cls.dtype_cls is type(dtype) and dtype.fields is None

    @classmethod
    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
        """
        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
        ----------
        dtype : TBaseDType
            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.
        """

        if cls._check_native_dtype(dtype):
            return cls(length=dtype.itemsize)
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    def to_native_dtype(self) -> np.dtypes.VoidDType[int]:
        """
        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.
        """
        # Numpy does not allow creating a void type
        # by invoking np.dtypes.VoidDType directly
        return cast("np.dtypes.VoidDType[int]", np.dtype(f"V{self.length}"))

    @classmethod
    def _check_json_v2(cls, data: DTypeJSON) -> TypeGuard[RawBytesJSON_V2]:
        """
        Check that the input is a valid representation of this class in Zarr V2.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to check.

        Returns
        -------
        True if the input is a valid representation of this class in Zarr V3, False otherwise.

        """
        return (
            check_dtype_spec_v2(data)
            and isinstance(data["name"], str)
            and re.match(r"^\|V\d+$", data["name"]) is not None
            and data["object_codec_id"] is None
        )

    @classmethod
    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[RawBytesJSON_V3]:
        """
        Check that the input is a valid JSON representation of this class in Zarr V3.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to check.

        Returns
        -------
        TypeGuard[RawBytesJSON_V3]
            True if the input is a valid representation of this class in Zarr V3, False
            otherwise.
        """
        return (
            isinstance(data, dict)
            and set(data.keys()) == {"name", "configuration"}
            and data["name"] == cls._zarr_v3_name
            and isinstance(data["configuration"], dict)
            and set(data["configuration"].keys()) == {"length_bytes"}
            and isinstance(data["configuration"]["length_bytes"], int)
        )

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of RawBytes from Zarr V2-flavored JSON.

        This method checks if the input data is a valid representation of
        RawBytes in Zarr V2. If so, it returns a new instance of
        RawBytes with a ``length`` as specified in the input data.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to parse.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input data is not a valid representation of this class.
        """
        if cls._check_json_v2(data):
            name = data["name"]
            return cls(length=int(name[2:]))
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a string like '|V1', '|V2', etc"
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of RawBytes from Zarr V3-flavored JSON.

        This method checks if the input data is a valid representation of
        RawBytes in Zarr V3. If so, it returns a new instance of
        RawBytes with a ``length`` as specified in the input data.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to parse.

        Returns
        -------
        RawBytes
            An instance of RawBytes.

        Raises
        ------
        DataTypeValidationError
            If the input data is not a valid representation of this class.
        """
        if cls._check_json_v3(data):
            return cls(length=data["configuration"]["length_bytes"])
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> RawBytesJSON_V2: ...

    @overload
    def to_json(self, zarr_format: Literal[3]) -> RawBytesJSON_V3: ...

    def to_json(self, zarr_format: ZarrFormat) -> RawBytesJSON_V2 | RawBytesJSON_V3:
        """
        Generate a JSON representation of this data type.

        Parameters
        ----------
        zarr_format : ZarrFormat
            The zarr format version.

        Returns
        -------
        RawBytesJSON_V2 | RawBytesJSON_V3
            The JSON-serializable representation of the data type.
        """
        if zarr_format == 2:
            return {"name": self.to_native_dtype().str, "object_codec_id": None}
        elif zarr_format == 3:
            v3_unstable_dtype_warning(self)
            return {"name": self._zarr_v3_name, "configuration": {"length_bytes": self.length}}
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    def _check_scalar(self, data: object) -> TypeGuard[np.bytes_ | str | bytes | np.void]:
        """
        Check if the provided data can be cast to np.void.

        This method is used to verify if the input data can be considered as a
        scalar of bytes-like type, which includes np.bytes_, np.void, strings, and bytes objects.

        Parameters
        ----------
        data : object
            The data to check.

        Returns
        -------
        TypeGuard[np.bytes_ | str | bytes | np.void]
            True if the data is void-scalar-like, False otherwise.
        """
        return isinstance(data, np.bytes_ | str | bytes | np.void)

    def _cast_scalar_unchecked(self, data: object) -> np.void:
        """
        Cast the provided scalar data to np.void.

        Parameters
        ----------
        data : BytesLike
            The data to cast.

        Returns
        -------
        np.void
            The casted data as a NumPy void scalar.

        Notes
        -----
        This method does not perform any type checking.
        The input data must be castable to np.void.
        """
        native_dtype = self.to_native_dtype()
        # Without the second argument, NumPy will return a void scalar for dtype V1.
        # The second argument ensures that, if native_dtype is something like V10,
        # the result will actually be a V10 scalar.
        return native_dtype.type(data, native_dtype)

    def cast_scalar(self, data: object) -> np.void:
        """
        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
        ----------
        data : object
            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.
        """
        if self._check_scalar(data):
            return self._cast_scalar_unchecked(data)
        msg = (
            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
            f"data type {self}."
        )
        raise TypeError(msg)

    def default_scalar(self) -> np.void:
        """
        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.
        """
        return self.to_native_dtype().type(("\x00" * self.length).encode("ascii"))

    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
        """
        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
        ----------
        data : object
            The scalar to convert.
        zarr_format : ZarrFormat
            The zarr format version.

        Returns
        -------
        str
            A string representation of the scalar.
        """
        as_bytes = self.cast_scalar(data)
        return base64.standard_b64encode(as_bytes.tobytes()).decode("ascii")

    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.void:
        """
        Read a JSON-serializable value as a np.void.

        Parameters
        ----------
        data : JSON
            The JSON-serializable value.
        zarr_format : ZarrFormat
            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.
        """
        if check_json_str(data):
            return self.to_native_dtype().type(base64.standard_b64decode(data))
        raise TypeError(f"Invalid type: {data}. Expected a string.")  # pragma: no cover

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return self.length

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

__post_init__ 

__post_init__() -> None

We don't allow instances of this class with length less than 1 because there is no way such a data type can contain actual data.

Source code in zarr/core/dtype/npy/bytes.py 
577
578
579
580
581
582
583
def __post_init__(self) -> None:
    """
    We don't allow instances of this class with length less than 1 because there is no way such
    a data type can contain actual data.
    """
    if self.length < 1:
        raise ValueError(f"length must be >= 1, got {self.length}.")

cast_scalar 

cast_scalar(data: object) -> void

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:

  • data (object) –

    The data to be cast to a NumPy void scalar.

Returns:

  • void –

    The data cast as a NumPy void scalar.

Raises:

  • TypeError –

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

Source code in zarr/core/dtype/npy/bytes.py 
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
def cast_scalar(self, data: object) -> np.void:
    """
    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
    ----------
    data : object
        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.
    """
    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> void

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:

  • void –

    The default scalar value.

Source code in zarr/core/dtype/npy/bytes.py 
864
865
866
867
868
869
870
871
872
873
874
875
876
def default_scalar(self) -> np.void:
    """
    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.
    """
    return self.to_native_dtype().type(("\x00" * self.length).encode("ascii"))

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> void

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • void –

    The NumPy void scalar.

Raises:

  • TypeError –

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

Source code in zarr/core/dtype/npy/bytes.py 
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.void:
    """
    Read a JSON-serializable value as a np.void.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        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.
    """
    if check_json_str(data):
        return self.to_native_dtype().type(base64.standard_b64decode(data))
    raise TypeError(f"Invalid type: {data}. Expected a string.")  # pragma: no cover

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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:

  • dtype (TBaseDType) –

    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.

Source code in zarr/core/dtype/npy/bytes.py 
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    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
    ----------
    dtype : TBaseDType
        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.
    """

    if cls._check_native_dtype(dtype):
        return cls(length=dtype.itemsize)
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(zarr_format: Literal[2]) -> RawBytesJSON_V2

to_json(zarr_format: Literal[3]) -> RawBytesJSON_V3

to_json(
    zarr_format: ZarrFormat,
) -> RawBytesJSON_V2 | RawBytesJSON_V3

Generate a JSON representation of this data type.

Parameters:

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

Source code in zarr/core/dtype/npy/bytes.py 
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
def to_json(self, zarr_format: ZarrFormat) -> RawBytesJSON_V2 | RawBytesJSON_V3:
    """
    Generate a JSON representation of this data type.

    Parameters
    ----------
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    RawBytesJSON_V2 | RawBytesJSON_V3
        The JSON-serializable representation of the data type.
    """
    if zarr_format == 2:
        return {"name": self.to_native_dtype().str, "object_codec_id": None}
    elif zarr_format == 3:
        v3_unstable_dtype_warning(self)
        return {"name": self._zarr_v3_name, "configuration": {"length_bytes": self.length}}
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> str

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:

  • data (object) –

    The scalar to convert.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • str –

    A string representation of the scalar.

Source code in zarr/core/dtype/npy/bytes.py 
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
    """
    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
    ----------
    data : object
        The scalar to convert.
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    str
        A string representation of the scalar.
    """
    as_bytes = self.cast_scalar(data)
    return base64.standard_b64encode(as_bytes.tobytes()).decode("ascii")

to_native_dtype 

to_native_dtype() -> VoidDType[int]

Create a NumPy void dtype from this RawBytes ZDType.

Returns:

  • VoidDType[int] –

    A NumPy data type object representing raw bytes with a specified length.

Source code in zarr/core/dtype/npy/bytes.py 
643
644
645
646
647
648
649
650
651
652
653
654
def to_native_dtype(self) -> np.dtypes.VoidDType[int]:
    """
    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.
    """
    # Numpy does not allow creating a void type
    # by invoking np.dtypes.VoidDType directly
    return cast("np.dtypes.VoidDType[int]", np.dtype(f"V{self.length}"))

RawBytesJSON_V2

Bases: 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
    }
Source code in zarr/core/dtype/npy/bytes.py 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
class RawBytesJSON_V2(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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).


    Examples
    --------
    ```python

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

RawBytesJSON_V3

Bases: 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
    }
}
Source code in zarr/core/dtype/npy/bytes.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
class RawBytesJSON_V3(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
    --------
    ```python
    {
        "name": "raw_bytes",
        "configuration": {
            "length_bytes": 12
        }
    }
    ```
    """

configuration instance-attribute 

configuration: ReadOnly[TConfig]

The configuration of the object.

name instance-attribute 

name: ReadOnly[TName]

The name of the object.

Structured dataclass

Bases: ZDType[VoidDType[int], void], 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:

References

This data type does not have a Zarr V3 specification.

The Zarr V2 data type specification can be found here.

Source code in zarr/core/dtype/npy/structured.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
@dataclass(frozen=True, kw_only=True)
class Structured(ZDType[np.dtypes.VoidDType[int], np.void], 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
    ----------
    fields : Sequence[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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).
    """

    _zarr_v3_name: ClassVar[Literal["structured"]] = "structured"
    dtype_cls = np.dtypes.VoidDType  # type: ignore[assignment]
    fields: tuple[tuple[str, ZDType[TBaseDType, TBaseScalar]], ...]

    def __post_init__(self) -> None:
        if len(self.fields) < 1:
            raise ValueError(f"must have at least one field. Got {self.fields!r}")

    @classmethod
    def _check_native_dtype(cls, dtype: TBaseDType) -> TypeGuard[np.dtypes.VoidDType[int]]:
        """
        Check that this dtype is a numpy structured dtype

        Parameters
        ----------
        dtype : np.dtypes.DTypeLike
            The dtype to check.

        Returns
        -------
        TypeGuard[np.dtypes.VoidDType]
            True if the dtype matches, False otherwise.
        """
        return isinstance(dtype, cls.dtype_cls) and dtype.fields is not None

    @classmethod
    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
        """
        Create a Structured ZDType from a native NumPy data type.

        Parameters
        ----------
        dtype : TBaseDType
            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.
        """
        from zarr.core.dtype import get_data_type_from_native_dtype

        fields: list[tuple[str, ZDType[TBaseDType, TBaseScalar]]] = []
        if cls._check_native_dtype(dtype):
            # fields of a structured numpy dtype are either 2-tuples or 3-tuples. we only
            # care about the first element in either case.
            for key, (dtype_instance, *_) in dtype.fields.items():  # type: ignore[union-attr]
                dtype_wrapped = get_data_type_from_native_dtype(dtype_instance)
                fields.append((key, dtype_wrapped))

            return cls(fields=tuple(fields))
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    def to_native_dtype(self) -> np.dtypes.VoidDType[int]:
        """
        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.
        """

        return cast(
            "np.dtypes.VoidDType[int]",
            np.dtype([(key, dtype.to_native_dtype()) for (key, dtype) in self.fields]),
        )

    @classmethod
    def _check_json_v2(
        cls,
        data: DTypeJSON,
    ) -> TypeGuard[StructuredJSON_V2]:
        """
        Check if the input is a valid JSON representation of a Structured data type
        for Zarr V2.

        The input data must be a mapping that contains a "name" key that is not a str,
        and an "object_codec_id" key that is None.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to check.

        Returns
        -------
        TypeGuard[StructuredJSON_V2]
            True if the input is a valid JSON representation of a Structured data type
            for Zarr V2, False otherwise.
        """
        return (
            check_dtype_spec_v2(data)
            and not isinstance(data["name"], str)
            and check_structured_dtype_name_v2(data["name"])
            and data["object_codec_id"] is None
        )

    @classmethod
    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[StructuredJSON_V3]:
        """
        Check that the input is a valid JSON representation of this class in Zarr V3.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to check.

        Returns
        -------
        TypeGuard[StructuredJSON_V3]
            True if the input is a valid JSON representation of a structured data type for Zarr V3,
            False otherwise.
        """

        return (
            isinstance(data, dict)
            and set(data.keys()) == {"name", "configuration"}
            and data["name"] == cls._zarr_v3_name
            and isinstance(data["configuration"], dict)
            and set(data["configuration"].keys()) == {"fields"}
        )

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        # avoid circular import
        from zarr.core.dtype import get_data_type_from_json

        if cls._check_json_v2(data):
            # structured dtypes are constructed directly from a list of lists
            # note that we do not handle the object codec here! this will prevent structured
            # dtypes from containing object dtypes.
            return cls(
                fields=tuple(  # type: ignore[misc]
                    (  # type: ignore[misc]
                        f_name,
                        get_data_type_from_json(
                            {"name": f_dtype, "object_codec_id": None}, zarr_format=2
                        ),
                    )
                    for f_name, f_dtype in data["name"]
                )
            )
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a JSON array of arrays"
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        # avoid circular import
        from zarr.core.dtype import get_data_type_from_json

        if cls._check_json_v3(data):
            config = data["configuration"]
            meta_fields = config["fields"]
            return cls(
                fields=tuple(
                    (f_name, get_data_type_from_json(f_dtype, zarr_format=3))  # type: ignore[misc]
                    for f_name, f_dtype in meta_fields
                )
            )
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a JSON object with the key {cls._zarr_v3_name!r}"
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> StructuredJSON_V2: ...

    @overload
    def to_json(self, zarr_format: Literal[3]) -> StructuredJSON_V3: ...

    def to_json(self, zarr_format: ZarrFormat) -> StructuredJSON_V2 | StructuredJSON_V3:
        """
        Convert the structured data type to a JSON-serializable form.

        Parameters
        ----------
        zarr_format : ZarrFormat
            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.
        """
        if zarr_format == 2:
            fields = [
                [f_name, f_dtype.to_json(zarr_format=zarr_format)["name"]]
                for f_name, f_dtype in self.fields
            ]
            return {"name": fields, "object_codec_id": None}
        elif zarr_format == 3:
            v3_unstable_dtype_warning(self)
            fields = [
                [f_name, f_dtype.to_json(zarr_format=zarr_format)]  # type: ignore[list-item]
                for f_name, f_dtype in self.fields
            ]
            base_dict = {
                "name": self._zarr_v3_name,
                "configuration": {"fields": fields},
            }
            return cast("StructuredJSON_V3", base_dict)
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    def _check_scalar(self, data: object) -> TypeGuard[StructuredScalarLike]:
        # TODO: implement something more precise here!
        """
        Check that the input is a valid scalar value for this structured data type.

        Parameters
        ----------
        data : object
            The scalar value to check.

        Returns
        -------
        TypeGuard[StructuredScalarLike]
            Whether the input is a valid scalar value for this structured data type.
        """
        return isinstance(data, (bytes, list, tuple, int, np.void))

    def _cast_scalar_unchecked(self, data: StructuredScalarLike) -> np.void:
        """
        Cast a python object to a numpy structured scalar without type checking.

        Parameters
        ----------
        data : StructuredScalarLike
            The data to cast.

        Returns
        -------
        np.void
            The casted data as a numpy structured scalar.

        Notes
        -----
        This method does not perform any type checking.
        The input data must be castable to a numpy structured scalar.

        """
        na_dtype = self.to_native_dtype()
        if isinstance(data, bytes):
            res = np.frombuffer(data, dtype=na_dtype)[0]
        elif isinstance(data, list | tuple):
            res = np.array([tuple(data)], dtype=na_dtype)[0]
        else:
            res = np.array([data], dtype=na_dtype)[0]
        return cast("np.void", res)

    def cast_scalar(self, data: object) -> np.void:
        """
        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
        ----------
        data : object
            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.
        """

        if self._check_scalar(data):
            return self._cast_scalar_unchecked(data)
        msg = (
            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
            f"data type {self}."
        )
        raise TypeError(msg)

    def default_scalar(self) -> np.void:
        """
        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.
        """

        return self._cast_scalar_unchecked(0)

    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.void:
        """
        Read a JSON-serializable value as a NumPy structured scalar.

        Parameters
        ----------
        data : JSON
            The JSON-serializable value.
        zarr_format : ZarrFormat
            The zarr format version.

        Returns
        -------
        np.void
            The NumPy structured scalar.

        Raises
        ------
        TypeError
            If the input is not a base64-encoded string.
        """
        if check_json_str(data):
            as_bytes = bytes_from_json(data, zarr_format=zarr_format)
            dtype = self.to_native_dtype()
            return cast("np.void", np.array([as_bytes]).view(dtype)[0])
        raise TypeError(f"Invalid type: {data}. Expected a string.")

    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
        """
        Convert a scalar to a JSON-serializable string representation.

        Parameters
        ----------
        data : object
            The scalar to convert.
        zarr_format : ZarrFormat
            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.
        """
        return bytes_to_json(self.cast_scalar(data).tobytes(), zarr_format)

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return self.to_native_dtype().itemsize

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> void

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:

  • data (object) –

    The data to be cast to a NumPy structured scalar.

Returns:

  • void –

    The data cast as a NumPy structured scalar.

Raises:

  • TypeError –

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

Source code in zarr/core/dtype/npy/structured.py 
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
def cast_scalar(self, data: object) -> np.void:
    """
    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
    ----------
    data : object
        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.
    """

    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> void

Get the default scalar value for this structured data type.

Returns:

  • void –

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

Source code in zarr/core/dtype/npy/structured.py 
408
409
410
411
412
413
414
415
416
417
418
419
def default_scalar(self) -> np.void:
    """
    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.
    """

    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> void

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • void –

    The NumPy structured scalar.

Raises:

  • TypeError –

    If the input is not a base64-encoded string.

Source code in zarr/core/dtype/npy/structured.py 
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.void:
    """
    Read a JSON-serializable value as a NumPy structured scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    np.void
        The NumPy structured scalar.

    Raises
    ------
    TypeError
        If the input is not a base64-encoded string.
    """
    if check_json_str(data):
        as_bytes = bytes_from_json(data, zarr_format=zarr_format)
        dtype = self.to_native_dtype()
        return cast("np.void", np.array([as_bytes]).view(dtype)[0])
    raise TypeError(f"Invalid type: {data}. Expected a string.")

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

Create a Structured ZDType from a native NumPy data type.

Parameters:

  • dtype (TBaseDType) –

    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.

Source code in zarr/core/dtype/npy/structured.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create a Structured ZDType from a native NumPy data type.

    Parameters
    ----------
    dtype : TBaseDType
        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.
    """
    from zarr.core.dtype import get_data_type_from_native_dtype

    fields: list[tuple[str, ZDType[TBaseDType, TBaseScalar]]] = []
    if cls._check_native_dtype(dtype):
        # fields of a structured numpy dtype are either 2-tuples or 3-tuples. we only
        # care about the first element in either case.
        for key, (dtype_instance, *_) in dtype.fields.items():  # type: ignore[union-attr]
            dtype_wrapped = get_data_type_from_native_dtype(dtype_instance)
            fields.append((key, dtype_wrapped))

        return cls(fields=tuple(fields))
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(zarr_format: Literal[2]) -> StructuredJSON_V2

to_json(zarr_format: Literal[3]) -> StructuredJSON_V3

to_json(
    zarr_format: ZarrFormat,
) -> StructuredJSON_V2 | StructuredJSON_V3

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

Parameters:

  • zarr_format (ZarrFormat) –

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

Returns:

Raises:

  • ValueError –

    If the zarr_format is not 2 or 3.

Source code in zarr/core/dtype/npy/structured.py 
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
def to_json(self, zarr_format: ZarrFormat) -> StructuredJSON_V2 | StructuredJSON_V3:
    """
    Convert the structured data type to a JSON-serializable form.

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        fields = [
            [f_name, f_dtype.to_json(zarr_format=zarr_format)["name"]]
            for f_name, f_dtype in self.fields
        ]
        return {"name": fields, "object_codec_id": None}
    elif zarr_format == 3:
        v3_unstable_dtype_warning(self)
        fields = [
            [f_name, f_dtype.to_json(zarr_format=zarr_format)]  # type: ignore[list-item]
            for f_name, f_dtype in self.fields
        ]
        base_dict = {
            "name": self._zarr_v3_name,
            "configuration": {"fields": fields},
        }
        return cast("StructuredJSON_V3", base_dict)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> str

Convert a scalar to a JSON-serializable string representation.

Parameters:

  • data (object) –

    The scalar to convert.

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/npy/structured.py 
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
    """
    Convert a scalar to a JSON-serializable string representation.

    Parameters
    ----------
    data : object
        The scalar to convert.
    zarr_format : ZarrFormat
        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.
    """
    return bytes_to_json(self.cast_scalar(data).tobytes(), zarr_format)

to_native_dtype 

to_native_dtype() -> VoidDType[int]

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:

  • VoidDType[int] –

    The native NumPy void dtype representing the structured data type.

Source code in zarr/core/dtype/npy/structured.py 
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def to_native_dtype(self) -> np.dtypes.VoidDType[int]:
    """
    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.
    """

    return cast(
        "np.dtypes.VoidDType[int]",
        np.dtype([(key, dtype.to_native_dtype()) for (key, dtype) in self.fields]),
    )

StructuredJSON_V2

Bases: DTypeConfig_V2[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
}
Source code in zarr/core/dtype/npy/structured.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
class StructuredJSON_V2(DTypeConfig_V2[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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

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

StructuredJSON_V3

Bases: NamedConfig[Literal['structured'], dict[str, Sequence[Sequence[str | 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"],
        ]
    }
}
Source code in zarr/core/dtype/npy/structured.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
class StructuredJSON_V3(
    NamedConfig[Literal["structured"], dict[str, Sequence[Sequence[str | DTypeJSON]]]]
):
    """
    A JSON representation of a structured data type in Zarr V3.

    References
    ----------
    This representation is not currently defined in an external specification.

    Examples
    --------
    ```python
    {
        "name": "structured",
        "configuration": {
            "fields": [
                ["f0", "int32],
                ["f1", "float64"],
            ]
        }
    }
    ```
    """

configuration instance-attribute 

configuration: ReadOnly[TConfig]

The configuration of the object.

name instance-attribute 

name: ReadOnly[TName]

The name of the object.

TimeDelta64 dataclass

Bases: TimeDTypeBase[TimeDelta64DType, timedelta64], 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_cls (Type[dtypesTimeDelta64DType]) –

    The NumPy dtype class for this data type.

  • scale_factor (int) –

    The scale factor for this data type.

  • unit (DateTimeUnit) –

    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

Source code in zarr/core/dtype/npy/time.py 
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
@dataclass(frozen=True, kw_only=True, slots=True)
class TimeDelta64(TimeDTypeBase[np.dtypes.TimeDelta64DType, np.timedelta64], 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_cls : Type[np.dtypesTimeDelta64DType]
        The NumPy dtype class for this data type.
    scale_factor : int
        The scale factor for this data type.
    unit : DateTimeUnit
        The unit for this data type.

    References
    ----------
    The Zarr V2 representation of this data type is defined in the Zarr V2
    [specification document](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

    The Zarr V3 representation of this data type is defined in the ``numpy.timedelta64``
    [specification document](https://github.com/zarr-developers/zarr-extensions/tree/main/data-types/numpy.timedelta64)
    """

    # mypy infers the type of np.dtypes.TimeDelta64DType to be
    # "Callable[[Literal['Y', 'M', 'W', 'D'] | Literal['h', 'm', 's', 'ms', 'us', 'ns', 'ps', 'fs', 'as']], Never]"
    dtype_cls = np.dtypes.TimeDelta64DType  # type: ignore[assignment]
    unit: DateTimeUnit = "generic"
    scale_factor: int = 1
    _zarr_v3_name: ClassVar[Literal["numpy.timedelta64"]] = "numpy.timedelta64"
    _zarr_v2_names: ClassVar[tuple[Literal[">m8"], Literal["<m8"]]] = (">m8", "<m8")
    _numpy_name: ClassVar[Literal["timedelta64"]] = "timedelta64"

    @classmethod
    def _check_json_v2(cls, data: DTypeJSON) -> TypeGuard[TimeDelta64JSON_V2]:
        """
        Validate that the provided JSON input accurately represents a NumPy timedelta64 data type,
        which could be in the form of strings like "<m8" or ">m8[10s]". This method serves as a type
        guard, helping to refine the type of unknown JSON input by confirming its adherence to the
        expected format for NumPy timedelta64 data types.

        The JSON input should contain a "name" key with a value that matches the expected string
        pattern for NumPy timedelta64 data types. The pattern includes an optional unit enclosed
        within square brackets, following the base type identifier.

        Returns
        -------
        bool
            True if the JSON input is a valid representation of this class,
            otherwise False.
        """
        if not check_dtype_spec_v2(data):
            return False
        name = data["name"]
        # match <m[ns], >m[M], etc
        # consider making this a standalone function
        if not isinstance(name, str):
            return False
        if not name.startswith(cls._zarr_v2_names):
            return False
        if len(name) == 3:
            # no unit, and
            # we already checked that this string is either <m8 or >m8
            return True
        else:
            return name[4:-1].endswith(DATETIME_UNIT) and name[-1] == "]"

    @classmethod
    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[DateTime64JSON_V3]:
        """
        Check that the input is a valid JSON representation of this class in Zarr V3.

        Returns
        -------
        TypeGuard[DateTime64JSON_V3]
            True if the JSON input is a valid representation of this class,
            otherwise False.
        """
        return (
            isinstance(data, dict)
            and set(data.keys()) == {"name", "configuration"}
            and data["name"] == cls._zarr_v3_name
            and isinstance(data["configuration"], dict)
            and set(data["configuration"].keys()) == {"unit", "scale_factor"}
        )

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create a TimeDelta64 from a Zarr V2-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        TimeDelta64
            An instance of TimeDelta64.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class.
        """
        if cls._check_json_v2(data):
            name = data["name"]
            return cls.from_native_dtype(np.dtype(name))
        msg = (
            f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a string "
            f"representation of an instance of {cls.dtype_cls}"
        )
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create a TimeDelta64 from a Zarr V3-flavored JSON.

        The JSON representation of a TimeDelta64 in Zarr V3 is a dict with a 'name' key
        with the value 'numpy.timedelta64', and a 'configuration' key with a value of a dict
        with a 'unit' key and a 'scale_factor' key.

        For example:

        ```json
        {
            "name": "numpy.timedelta64",
            "configuration": {
                "unit": "generic",
                "scale_factor": 1
            }
        }
        ```

        """
        if cls._check_json_v3(data):
            unit = data["configuration"]["unit"]
            scale_factor = data["configuration"]["scale_factor"]
            return cls(unit=unit, scale_factor=scale_factor)
        msg = (
            f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected a dict "
            f"with a 'name' key with the value 'numpy.timedelta64', "
            "and a 'configuration' key with a value of a dict with a 'unit' key and a "
            "'scale_factor' key"
        )
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> TimeDelta64JSON_V2: ...
    @overload
    def to_json(self, zarr_format: Literal[3]) -> TimeDelta64JSON_V3: ...

    def to_json(self, zarr_format: ZarrFormat) -> TimeDelta64JSON_V2 | TimeDelta64JSON_V3:
        """
        Serialize this data type to JSON.

        Parameters
        ----------
        zarr_format : ZarrFormat
            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.
        """
        if zarr_format == 2:
            name = self.to_native_dtype().str
            return {"name": name, "object_codec_id": None}
        elif zarr_format == 3:
            return {
                "name": self._zarr_v3_name,
                "configuration": {"unit": self.unit, "scale_factor": self.scale_factor},
            }
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    def _check_scalar(self, data: object) -> TypeGuard[TimeDeltaLike]:
        """
        Check if the input is a scalar of this data type.

        Parameters
        ----------
        data : object
            The object to check.

        Returns
        -------
        TypeGuard[TimeDeltaLike]
            True if the input is a scalar of this data type, False otherwise.
        """
        if data is None:
            return True
        return isinstance(data, str | int | bytes | np.timedelta64 | timedelta)

    def _cast_scalar_unchecked(self, data: TimeDeltaLike) -> np.timedelta64:
        """
        Cast the provided scalar input to a numpy timedelta64 without any type checking.

        This method assumes that the input data is already a valid scalar of this data type,
        and does not perform any validation or type checks. It directly casts the input
        to a numpy timedelta64 scalar using the unit and scale factor defined in the class.

        Parameters
        ----------
        data : TimeDeltaLike
            The scalar input data to cast.

        Returns
        -------
        numpy.timedelta64
            The input data cast as a numpy timedelta64 scalar.
        """
        return self.to_native_dtype().type(data, f"{self.scale_factor}{self.unit}")

    def cast_scalar(self, data: object) -> np.timedelta64:
        """
        Cast the input to a numpy timedelta64 scalar. If the input is not a scalar of this data type,
        raise a TypeError.
        """
        if self._check_scalar(data):
            return self._cast_scalar_unchecked(data)
        msg = (
            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
            f"data type {self}."
        )
        raise TypeError(msg)

    def default_scalar(self) -> np.timedelta64:
        """
        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.
        """
        return np.timedelta64("NaT")

    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.timedelta64:
        """
        Create a scalar of this data type from JSON input.

        Parameters
        ----------
        data : JSON
            The JSON representation of the scalar value.
        zarr_format : int
            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.
        """
        if check_json_time(data):
            return self.to_native_dtype().type(data, f"{self.scale_factor}{self.unit}")
        raise TypeError(f"Invalid type: {data}. Expected an integer.")  # pragma: no cover

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> timedelta64

Cast the input to a numpy timedelta64 scalar. If the input is not a scalar of this data type, raise a TypeError.

Source code in zarr/core/dtype/npy/time.py 
550
551
552
553
554
555
556
557
558
559
560
561
def cast_scalar(self, data: object) -> np.timedelta64:
    """
    Cast the input to a numpy timedelta64 scalar. If the input is not a scalar of this data type,
    raise a TypeError.
    """
    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> timedelta64

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.

Source code in zarr/core/dtype/npy/time.py 
563
564
565
566
567
568
569
570
def default_scalar(self) -> np.timedelta64:
    """
    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.
    """
    return np.timedelta64("NaT")

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> timedelta64

Create a scalar of this data type from JSON input.

Parameters:

  • data (JSON) –

    The JSON representation of the scalar value.

  • zarr_format (int) –

    The zarr format to use for the JSON representation.

Returns:

Raises:

  • TypeError –

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

Source code in zarr/core/dtype/npy/time.py 
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.timedelta64:
    """
    Create a scalar of this data type from JSON input.

    Parameters
    ----------
    data : JSON
        The JSON representation of the scalar value.
    zarr_format : int
        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.
    """
    if check_json_time(data):
        return self.to_native_dtype().type(data, f"{self.scale_factor}{self.unit}")
    raise TypeError(f"Invalid type: {data}. Expected an integer.")  # pragma: no cover

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (TBaseDType) –

    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.

Source code in zarr/core/dtype/npy/time.py 
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an instance of this class from a native NumPy data type.

    Parameters
    ----------
    dtype : TBaseDType
        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.
    """

    if cls._check_native_dtype(dtype):
        unit, scale_factor = np.datetime_data(dtype.name)
        unit = cast("DateTimeUnit", unit)
        return cls(
            unit=unit,
            scale_factor=scale_factor,
            endianness=get_endianness_from_numpy_dtype(dtype),
        )
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(zarr_format: Literal[2]) -> TimeDelta64JSON_V2

to_json(zarr_format: Literal[3]) -> TimeDelta64JSON_V3

to_json(
    zarr_format: ZarrFormat,
) -> TimeDelta64JSON_V2 | TimeDelta64JSON_V3

Serialize this data type to JSON.

Parameters:

  • zarr_format (ZarrFormat) –

    The Zarr format version (2 or 3).

Returns:

Raises:

  • ValueError –

    If the zarr_format is not 2 or 3.

Source code in zarr/core/dtype/npy/time.py 
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
def to_json(self, zarr_format: ZarrFormat) -> TimeDelta64JSON_V2 | TimeDelta64JSON_V3:
    """
    Serialize this data type to JSON.

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        name = self.to_native_dtype().str
        return {"name": name, "object_codec_id": None}
    elif zarr_format == 3:
        return {
            "name": self._zarr_v3_name,
            "configuration": {"unit": self.unit, "scale_factor": self.scale_factor},
        }
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> int

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

Parameters:

  • data (object) –

    The python object to convert.

  • zarr_format (ZarrFormat) –

    The Zarr format version (2 or 3).

Returns:

  • int –

    The JSON representation of the scalar.

Source code in zarr/core/dtype/npy/time.py 
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
    """
    Convert a python object to a JSON representation of a datetime64 or timedelta64 scalar.

    Parameters
    ----------
    data : object
        The python object to convert.
    zarr_format : ZarrFormat
        The Zarr format version (2 or 3).

    Returns
    -------
    int
        The JSON representation of the scalar.
    """
    return datetimelike_to_int(data)  # type: ignore[arg-type]

to_native_dtype 

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.

Source code in zarr/core/dtype/npy/time.py 
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
def to_native_dtype(self) -> BaseTimeDType_co:
    # Numpy does not allow creating datetime64 or timedelta64 via
    # np.dtypes.{dtype_name}()
    # so we use np.dtype with a formatted string.
    """
    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_string = f"{self._numpy_name}[{self.scale_factor}{self.unit}]"
    return np.dtype(dtype_string).newbyteorder(endianness_to_numpy_str(self.endianness))  # type: ignore[return-value]

TimeDelta64JSON_V2

Bases: 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
}
Source code in zarr/core/dtype/npy/time.py 
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
class TimeDelta64JSON_V2(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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).


    Examples
    --------
    ```python
    {
        "name": "<m8[1s]",
        "object_codec_id": None
    }
    ```
    """

TimeDelta64JSON_V3

Bases: 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
        }
}
Source code in zarr/core/dtype/npy/time.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
class TimeDelta64JSON_V3(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](https://zarr-specs.readthedocs.io/en/latest/spec/v3/datatypes.html#numpy-timedelta64).

    Examples
    --------
    ```python
    {
        "name": "numpy.timedelta64",
        "configuration": {
            "unit": "ms",
            "scale_factor": 1
            }
    }
    ```
    """

configuration instance-attribute 

configuration: ReadOnly[TConfig]

The configuration of the object.

name instance-attribute 

name: ReadOnly[TName]

The name of the object.

UInt16 dataclass

Bases: BaseInt[UInt16DType, uint16], 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_cls (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.

Source code in zarr/core/dtype/npy/int.py 
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
@dataclass(frozen=True, kw_only=True)
class UInt16(BaseInt[np.dtypes.UInt16DType, np.uint16], HasEndianness):
    """
    A Zarr data type for arrays containing 16-bit unsigned integers.

    Wraps the [`np.dtypes.UInt16DType`][numpy.dtypes.UInt16DType] data type. Scalars for this data type are instances of
    [`np.uint16`][numpy.uint16].

    Attributes
    ----------
    dtype_cls : np.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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
    """

    dtype_cls = np.dtypes.UInt16DType
    _zarr_v3_name: ClassVar[Literal["uint16"]] = "uint16"
    _zarr_v2_names: ClassVar[tuple[Literal[">u2"], Literal["<u2"]]] = (">u2", "<u2")

    @classmethod
    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
        """
        Create an instance of this data type from a np.dtype('uint16') instance.

        Parameters
        ----------
        dtype : np.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').
        """
        if cls._check_native_dtype(dtype):
            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    def to_native_dtype(self) -> np.dtypes.UInt16DType:
        """
        Convert the data type to a np.dtype('uint16') instance.

        Returns
        -------
        np.dtype
            The np.dtype('uint16') instance.
        """
        byte_order = endianness_to_numpy_str(self.endianness)
        return self.dtype_cls().newbyteorder(byte_order)

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from Zarr V2-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class.
        """
        if cls._check_json_v2(data):
            # Going via NumPy ensures that we get the endianness correct without
            # annoying string parsing.
            name = data["name"]
            return cls.from_native_dtype(np.dtype(name))
        msg = f"Invalid JSON representation of UInt16. Got {data!r}, expected one of the strings {cls._zarr_v2_names}."
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from Zarr V3-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class.
        """
        if cls._check_json_v3(data):
            return cls()
        msg = f"Invalid JSON representation of UInt16. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal[">u2", "<u2"], None]: ...

    @overload
    def to_json(self, zarr_format: Literal[3]) -> Literal["uint16"]: ...

    def to_json(
        self, zarr_format: ZarrFormat
    ) -> DTypeConfig_V2[Literal[">u2", "<u2"], None] | Literal["uint16"]:
        """
        Serialize this ZDType to v2- or v3-flavored JSON

        Parameters
        ----------
        zarr_format : ZarrFormat
            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.
        """
        if zarr_format == 2:
            name = self.to_native_dtype().str
            return {"name": name, "object_codec_id": None}
        elif zarr_format == 3:
            return self._zarr_v3_name
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 2

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> TIntScalar_co

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

Parameters:

  • data (object) –

    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.

Source code in zarr/core/dtype/npy/int.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def cast_scalar(self, data: object) -> TIntScalar_co:
    """
    Attempt to cast a given object to a NumPy integer scalar.

    Parameters
    ----------
    data : object
        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.
    """

    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> TIntScalar_co

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

Returns:

  • TIntScalar_co –

    The default value.

Source code in zarr/core/dtype/npy/int.py 
176
177
178
179
180
181
182
183
184
185
def default_scalar(self) -> TIntScalar_co:
    """
    Get the default value, which is 0 cast to this dtype.

    Returns
    -------
    TIntScalar_co
        The default value.
    """
    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TIntScalar_co

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • TIntScalar_co –

    The NumPy int scalar.

Raises:

  • TypeError –

    If the input is not a valid integer type.

Source code in zarr/core/dtype/npy/int.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TIntScalar_co:
    """
    Read a JSON-serializable value as a NumPy int scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    TIntScalar_co
        The NumPy int scalar.

    Raises
    ------
    TypeError
        If the input is not a valid integer type.
    """
    if check_json_int(data):
        return self._cast_scalar_unchecked(data)
    if check_json_intish_float(data):
        return self._cast_scalar_unchecked(int(data))
    raise TypeError(f"Invalid type: {data}. Expected an integer.")

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (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').

Source code in zarr/core/dtype/npy/int.py 
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an instance of this data type from a np.dtype('uint16') instance.

    Parameters
    ----------
    dtype : np.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').
    """
    if cls._check_native_dtype(dtype):
        return cls(endianness=get_endianness_from_numpy_dtype(dtype))
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[Literal[">u2", "<u2"], None]

to_json(zarr_format: Literal[3]) -> Literal['uint16']

to_json(
    zarr_format: ZarrFormat,
) -> (
    DTypeConfig_V2[Literal[">u2", "<u2"], None]
    | Literal["uint16"]
)

Serialize this ZDType to v2- or v3-flavored JSON

Parameters:

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/npy/int.py 
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
def to_json(
    self, zarr_format: ZarrFormat
) -> DTypeConfig_V2[Literal[">u2", "<u2"], None] | Literal["uint16"]:
    """
    Serialize this ZDType to v2- or v3-flavored JSON

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        name = self.to_native_dtype().str
        return {"name": name, "object_codec_id": None}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> int

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

Parameters:

  • data (object) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • int –

    The JSON-serializable form of the scalar.

Source code in zarr/core/dtype/npy/int.py 
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
    """
    Convert an object to a JSON serializable scalar. For the integer data types,
    the JSON form is a plain integer.

    Parameters
    ----------
    data : object
        The value to convert.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    int
        The JSON-serializable form of the scalar.
    """
    return int(self.cast_scalar(data))

to_native_dtype 

to_native_dtype() -> UInt16DType

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

Returns:

  • dtype –

    The np.dtype('uint16') instance.

Source code in zarr/core/dtype/npy/int.py 
749
750
751
752
753
754
755
756
757
758
759
def to_native_dtype(self) -> np.dtypes.UInt16DType:
    """
    Convert the data type to a np.dtype('uint16') instance.

    Returns
    -------
    np.dtype
        The np.dtype('uint16') instance.
    """
    byte_order = endianness_to_numpy_str(self.endianness)
    return self.dtype_cls().newbyteorder(byte_order)

UInt32 dataclass

Bases: BaseInt[UInt32DType, uint32], 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_cls (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.

Source code in zarr/core/dtype/npy/int.py 
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
@dataclass(frozen=True, kw_only=True)
class UInt32(BaseInt[np.dtypes.UInt32DType, np.uint32], HasEndianness):
    """
    A Zarr data type for arrays containing 32-bit unsigned integers.

    Wraps the [`np.dtypes.UInt32DType`][numpy.dtypes.UInt32DType] data type. Scalars for this data type are instances of
    [`np.uint32`][numpy.uint32].

    Attributes
    ----------
    dtype_cls : np.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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
    """

    dtype_cls = np.dtypes.UInt32DType
    _zarr_v3_name: ClassVar[Literal["uint32"]] = "uint32"
    _zarr_v2_names: ClassVar[tuple[Literal[">u4"], Literal["<u4"]]] = (">u4", "<u4")

    @classmethod
    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
        """
        Create a UInt32 from a np.dtype('uint32') instance.

        Parameters
        ----------
        dtype : TBaseDType
            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.
        """
        if cls._check_native_dtype(dtype):
            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    def to_native_dtype(self) -> np.dtypes.UInt32DType:
        """
        Create a NumPy unsigned 32-bit integer dtype instance from this UInt32 ZDType.

        Returns
        -------
        np.dtypes.UInt32DType
            The NumPy unsigned 32-bit integer dtype.
        """
        byte_order = endianness_to_numpy_str(self.endianness)
        return self.dtype_cls().newbyteorder(byte_order)

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from Zarr V2-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class 32-bit unsigned
            integer.
        """
        if cls._check_json_v2(data):
            # Going via NumPy ensures that we get the endianness correct without
            # annoying string parsing.
            name = data["name"]
            return cls.from_native_dtype(np.dtype(name))
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected one of the strings {cls._zarr_v2_names}."
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from Zarr V3-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class 32-bit unsigned
            integer.
        """
        if cls._check_json_v3(data):
            return cls()
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal[">u4", "<u4"], None]: ...
    @overload
    def to_json(self, zarr_format: Literal[3]) -> Literal["uint32"]: ...
    def to_json(
        self, zarr_format: ZarrFormat
    ) -> DTypeConfig_V2[Literal[">u4", "<u4"], None] | Literal["uint32"]:
        """
        Convert the data type to a JSON-serializable form.

        Parameters
        ----------
        zarr_format : ZarrFormat
            The Zarr format version.

        Returns
        -------
        DTypeConfig_V2[Literal[">u4", "<u4"], None] | Literal["uint32"]
            The JSON-serializable representation of the data type
        """
        if zarr_format == 2:
            name = self.to_native_dtype().str
            return {"name": name, "object_codec_id": None}
        elif zarr_format == 3:
            return self._zarr_v3_name
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 4

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> TIntScalar_co

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

Parameters:

  • data (object) –

    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.

Source code in zarr/core/dtype/npy/int.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def cast_scalar(self, data: object) -> TIntScalar_co:
    """
    Attempt to cast a given object to a NumPy integer scalar.

    Parameters
    ----------
    data : object
        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.
    """

    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> TIntScalar_co

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

Returns:

  • TIntScalar_co –

    The default value.

Source code in zarr/core/dtype/npy/int.py 
176
177
178
179
180
181
182
183
184
185
def default_scalar(self) -> TIntScalar_co:
    """
    Get the default value, which is 0 cast to this dtype.

    Returns
    -------
    TIntScalar_co
        The default value.
    """
    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TIntScalar_co

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • TIntScalar_co –

    The NumPy int scalar.

Raises:

  • TypeError –

    If the input is not a valid integer type.

Source code in zarr/core/dtype/npy/int.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TIntScalar_co:
    """
    Read a JSON-serializable value as a NumPy int scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    TIntScalar_co
        The NumPy int scalar.

    Raises
    ------
    TypeError
        If the input is not a valid integer type.
    """
    if check_json_int(data):
        return self._cast_scalar_unchecked(data)
    if check_json_intish_float(data):
        return self._cast_scalar_unchecked(int(data))
    raise TypeError(f"Invalid type: {data}. Expected an integer.")

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

Create a UInt32 from a np.dtype('uint32') instance.

Parameters:

  • dtype (TBaseDType) –

    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.

Source code in zarr/core/dtype/npy/int.py 
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create a UInt32 from a np.dtype('uint32') instance.

    Parameters
    ----------
    dtype : TBaseDType
        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.
    """
    if cls._check_native_dtype(dtype):
        return cls(endianness=get_endianness_from_numpy_dtype(dtype))
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[Literal[">u4", "<u4"], None]

to_json(zarr_format: Literal[3]) -> Literal['uint32']

to_json(
    zarr_format: ZarrFormat,
) -> (
    DTypeConfig_V2[Literal[">u4", "<u4"], None]
    | Literal["uint32"]
)

Convert the data type to a JSON-serializable form.

Parameters:

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • DTypeConfig_V2[Literal['>u4', '<u4'], None] | Literal['uint32'] –

    The JSON-serializable representation of the data type

Source code in zarr/core/dtype/npy/int.py 
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
def to_json(
    self, zarr_format: ZarrFormat
) -> DTypeConfig_V2[Literal[">u4", "<u4"], None] | Literal["uint32"]:
    """
    Convert the data type to a JSON-serializable form.

    Parameters
    ----------
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    DTypeConfig_V2[Literal[">u4", "<u4"], None] | Literal["uint32"]
        The JSON-serializable representation of the data type
    """
    if zarr_format == 2:
        name = self.to_native_dtype().str
        return {"name": name, "object_codec_id": None}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> int

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

Parameters:

  • data (object) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • int –

    The JSON-serializable form of the scalar.

Source code in zarr/core/dtype/npy/int.py 
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
    """
    Convert an object to a JSON serializable scalar. For the integer data types,
    the JSON form is a plain integer.

    Parameters
    ----------
    data : object
        The value to convert.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    int
        The JSON-serializable form of the scalar.
    """
    return int(self.cast_scalar(data))

to_native_dtype 

to_native_dtype() -> UInt32DType

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

Returns:

  • UInt32DType –

    The NumPy unsigned 32-bit integer dtype.

Source code in zarr/core/dtype/npy/int.py 
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
def to_native_dtype(self) -> np.dtypes.UInt32DType:
    """
    Create a NumPy unsigned 32-bit integer dtype instance from this UInt32 ZDType.

    Returns
    -------
    np.dtypes.UInt32DType
        The NumPy unsigned 32-bit integer dtype.
    """
    byte_order = endianness_to_numpy_str(self.endianness)
    return self.dtype_cls().newbyteorder(byte_order)

UInt64 dataclass

Bases: BaseInt[UInt64DType, uint64], 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 (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.

Source code in zarr/core/dtype/npy/int.py 
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
@dataclass(frozen=True, kw_only=True)
class UInt64(BaseInt[np.dtypes.UInt64DType, np.uint64], HasEndianness):
    """
    A Zarr data type for arrays containing 64-bit unsigned integers.

    Wraps the [`np.dtypes.UInt64DType`][numpy.dtypes.UInt64DType] data type. Scalars for this data type
    are instances of [`np.uint64`][numpy.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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
    """

    dtype_cls = np.dtypes.UInt64DType
    _zarr_v3_name: ClassVar[Literal["uint64"]] = "uint64"
    _zarr_v2_names: ClassVar[tuple[Literal[">u8"], Literal["<u8"]]] = (">u8", "<u8")

    def to_native_dtype(self) -> np.dtypes.UInt64DType:
        """
        Convert the data type to a native NumPy dtype.

        Returns
        -------
        np.dtypes.UInt64DType
            The native NumPy dtype.eeeeeeeeeeeeeeeee
        """
        byte_order = endianness_to_numpy_str(self.endianness)
        return self.dtype_cls().newbyteorder(byte_order)

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from Zarr V2-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class unsigned 64-bit
            integer.
        """
        if cls._check_json_v2(data):
            # Going via NumPy ensures that we get the endianness correct without
            # annoying string parsing.
            name = data["name"]
            return cls.from_native_dtype(np.dtype(name))
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected one of the strings {cls._zarr_v2_names}."
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from Zarr V3-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class unsigned 64-bit
            integer.
        """
        if cls._check_json_v3(data):
            return cls()
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal[">u8", "<u8"], None]: ...
    @overload
    def to_json(self, zarr_format: Literal[3]) -> Literal["uint64"]: ...

    def to_json(
        self, zarr_format: ZarrFormat
    ) -> DTypeConfig_V2[Literal[">u8", "<u8"], None] | Literal["uint64"]:
        """
        Convert the data type to a JSON-serializable form.

        Parameters
        ----------
        zarr_format : ZarrFormat
            The Zarr format version.

        Returns
        -------
        DTypeConfig_V2[Literal[">u8", "<u8"], None] | Literal["uint64"]
            The JSON-serializable representation of the data type.
        """
        if zarr_format == 2:
            name = self.to_native_dtype().str
            return {"name": name, "object_codec_id": None}
        elif zarr_format == 3:
            return self._zarr_v3_name
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    @classmethod
    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
        """
        Create an instance of this data type from a native NumPy dtype.

        Parameters
        ----------
        dtype : TBaseDType
            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.
        """
        if cls._check_native_dtype(dtype):
            return cls(endianness=get_endianness_from_numpy_dtype(dtype))
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 8

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> TIntScalar_co

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

Parameters:

  • data (object) –

    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.

Source code in zarr/core/dtype/npy/int.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def cast_scalar(self, data: object) -> TIntScalar_co:
    """
    Attempt to cast a given object to a NumPy integer scalar.

    Parameters
    ----------
    data : object
        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.
    """

    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> TIntScalar_co

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

Returns:

  • TIntScalar_co –

    The default value.

Source code in zarr/core/dtype/npy/int.py 
176
177
178
179
180
181
182
183
184
185
def default_scalar(self) -> TIntScalar_co:
    """
    Get the default value, which is 0 cast to this dtype.

    Returns
    -------
    TIntScalar_co
        The default value.
    """
    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TIntScalar_co

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • TIntScalar_co –

    The NumPy int scalar.

Raises:

  • TypeError –

    If the input is not a valid integer type.

Source code in zarr/core/dtype/npy/int.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TIntScalar_co:
    """
    Read a JSON-serializable value as a NumPy int scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    TIntScalar_co
        The NumPy int scalar.

    Raises
    ------
    TypeError
        If the input is not a valid integer type.
    """
    if check_json_int(data):
        return self._cast_scalar_unchecked(data)
    if check_json_intish_float(data):
        return self._cast_scalar_unchecked(int(data))
    raise TypeError(f"Invalid type: {data}. Expected an integer.")

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (TBaseDType) –

    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.

Source code in zarr/core/dtype/npy/int.py 
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an instance of this data type from a native NumPy dtype.

    Parameters
    ----------
    dtype : TBaseDType
        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.
    """
    if cls._check_native_dtype(dtype):
        return cls(endianness=get_endianness_from_numpy_dtype(dtype))
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[Literal[">u8", "<u8"], None]

to_json(zarr_format: Literal[3]) -> Literal['uint64']

to_json(
    zarr_format: ZarrFormat,
) -> (
    DTypeConfig_V2[Literal[">u8", "<u8"], None]
    | Literal["uint64"]
)

Convert the data type to a JSON-serializable form.

Parameters:

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • DTypeConfig_V2[Literal['>u8', '<u8'], None] | Literal['uint64'] –

    The JSON-serializable representation of the data type.

Source code in zarr/core/dtype/npy/int.py 
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
def to_json(
    self, zarr_format: ZarrFormat
) -> DTypeConfig_V2[Literal[">u8", "<u8"], None] | Literal["uint64"]:
    """
    Convert the data type to a JSON-serializable form.

    Parameters
    ----------
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    DTypeConfig_V2[Literal[">u8", "<u8"], None] | Literal["uint64"]
        The JSON-serializable representation of the data type.
    """
    if zarr_format == 2:
        name = self.to_native_dtype().str
        return {"name": name, "object_codec_id": None}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> int

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

Parameters:

  • data (object) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • int –

    The JSON-serializable form of the scalar.

Source code in zarr/core/dtype/npy/int.py 
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
    """
    Convert an object to a JSON serializable scalar. For the integer data types,
    the JSON form is a plain integer.

    Parameters
    ----------
    data : object
        The value to convert.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    int
        The JSON-serializable form of the scalar.
    """
    return int(self.cast_scalar(data))

to_native_dtype 

to_native_dtype() -> UInt64DType

Convert the data type to a native NumPy dtype.

Returns:

  • UInt64DType –

    The native NumPy dtype.eeeeeeeeeeeeeeeee

Source code in zarr/core/dtype/npy/int.py 
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
def to_native_dtype(self) -> np.dtypes.UInt64DType:
    """
    Convert the data type to a native NumPy dtype.

    Returns
    -------
    np.dtypes.UInt64DType
        The native NumPy dtype.eeeeeeeeeeeeeeeee
    """
    byte_order = endianness_to_numpy_str(self.endianness)
    return self.dtype_cls().newbyteorder(byte_order)

UInt8 dataclass

Bases: BaseInt[UInt8DType, 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_cls (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.

Source code in zarr/core/dtype/npy/int.py 
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
@dataclass(frozen=True, kw_only=True)
class UInt8(BaseInt[np.dtypes.UInt8DType, np.uint8]):
    """
    A Zarr data type for arrays containing 8-bit unsigned integers.

    Wraps the [`np.dtypes.UInt8DType`][numpy.dtypes.UInt8DType] data type. Scalars for this data type are instances of [`np.uint8`][numpy.uint8].

    Attributes
    ----------
    dtype_cls : np.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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding) and [Zarr V3](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst) specification documents for details.
    """

    dtype_cls = np.dtypes.UInt8DType
    _zarr_v3_name: ClassVar[Literal["uint8"]] = "uint8"
    _zarr_v2_names: ClassVar[tuple[Literal["|u1"]]] = ("|u1",)

    @classmethod
    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
        """
        Create a UInt8 from a np.dtype('uint8') instance.
        """
        if cls._check_native_dtype(dtype):
            return cls()
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    def to_native_dtype(self: Self) -> np.dtypes.UInt8DType:
        """
        Create a NumPy unsigned 8-bit integer dtype instance from this UInt8 ZDType.

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

        return self.dtype_cls()

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from Zarr V2-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class.
        """

        if cls._check_json_v2(data):
            return cls()
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v2_names[0]!r}"
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this data type from Zarr V3-flavored JSON.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input JSON is not a valid representation of this class.
        """
        if cls._check_json_v3(data):
            return cls()
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> DTypeConfig_V2[Literal["|u1"], None]: ...

    @overload
    def to_json(self, zarr_format: Literal[3]) -> Literal["uint8"]: ...

    def to_json(
        self, zarr_format: ZarrFormat
    ) -> DTypeConfig_V2[Literal["|u1"], None] | Literal["uint8"]:
        """
        Convert the data type to a JSON-serializable form.

        Parameters
        ----------
        zarr_format : ZarrFormat
            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.
        """
        if zarr_format == 2:
            # For Zarr format version 2, return a dictionary with the name and object codec ID.
            return {"name": self._zarr_v2_names[0], "object_codec_id": None}
        elif zarr_format == 3:
            # For Zarr format version 3, return the v3 name as a string.
            return self._zarr_v3_name
        # Raise an error if the zarr_format is neither 2 nor 3.
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    @property
    def item_size(self) -> int:
        """
        The size of a single scalar in bytes.

        Returns
        -------
        int
            The size of a single scalar in bytes.
        """
        return 1

item_size property 

item_size: int

The size of a single scalar in bytes.

Returns:

  • int –

    The size of a single scalar in bytes.

cast_scalar 

cast_scalar(data: object) -> TIntScalar_co

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

Parameters:

  • data (object) –

    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.

Source code in zarr/core/dtype/npy/int.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
def cast_scalar(self, data: object) -> TIntScalar_co:
    """
    Attempt to cast a given object to a NumPy integer scalar.

    Parameters
    ----------
    data : object
        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.
    """

    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> TIntScalar_co

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

Returns:

  • TIntScalar_co –

    The default value.

Source code in zarr/core/dtype/npy/int.py 
176
177
178
179
180
181
182
183
184
185
def default_scalar(self) -> TIntScalar_co:
    """
    Get the default value, which is 0 cast to this dtype.

    Returns
    -------
    TIntScalar_co
        The default value.
    """
    return self._cast_scalar_unchecked(0)

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TIntScalar_co

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

Parameters:

  • data (JSON) –

    The JSON-serializable value.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • TIntScalar_co –

    The NumPy int scalar.

Raises:

  • TypeError –

    If the input is not a valid integer type.

Source code in zarr/core/dtype/npy/int.py 
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TIntScalar_co:
    """
    Read a JSON-serializable value as a NumPy int scalar.

    Parameters
    ----------
    data : JSON
        The JSON-serializable value.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    TIntScalar_co
        The NumPy int scalar.

    Raises
    ------
    TypeError
        If the input is not a valid integer type.
    """
    if check_json_int(data):
        return self._cast_scalar_unchecked(data)
    if check_json_intish_float(data):
        return self._cast_scalar_unchecked(int(data))
    raise TypeError(f"Invalid type: {data}. Expected an integer.")

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

Create a UInt8 from a np.dtype('uint8') instance.

Source code in zarr/core/dtype/npy/int.py 
414
415
416
417
418
419
420
421
422
423
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create a UInt8 from a np.dtype('uint8') instance.
    """
    if cls._check_native_dtype(dtype):
        return cls()
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> DTypeConfig_V2[Literal["|u1"], None]

to_json(zarr_format: Literal[3]) -> Literal['uint8']

to_json(
    zarr_format: ZarrFormat,
) -> (
    DTypeConfig_V2[Literal["|u1"], None] | Literal["uint8"]
)

Convert the data type to a JSON-serializable form.

Parameters:

  • zarr_format (ZarrFormat) –

    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:

Source code in zarr/core/dtype/npy/int.py 
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
def to_json(
    self, zarr_format: ZarrFormat
) -> DTypeConfig_V2[Literal["|u1"], None] | Literal["uint8"]:
    """
    Convert the data type to a JSON-serializable form.

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """
    if zarr_format == 2:
        # For Zarr format version 2, return a dictionary with the name and object codec ID.
        return {"name": self._zarr_v2_names[0], "object_codec_id": None}
    elif zarr_format == 3:
        # For Zarr format version 3, return the v3 name as a string.
        return self._zarr_v3_name
    # Raise an error if the zarr_format is neither 2 nor 3.
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> int

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

Parameters:

  • data (object) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    The Zarr format version.

Returns:

  • int –

    The JSON-serializable form of the scalar.

Source code in zarr/core/dtype/npy/int.py 
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> int:
    """
    Convert an object to a JSON serializable scalar. For the integer data types,
    the JSON form is a plain integer.

    Parameters
    ----------
    data : object
        The value to convert.
    zarr_format : ZarrFormat
        The Zarr format version.

    Returns
    -------
    int
        The JSON-serializable form of the scalar.
    """
    return int(self.cast_scalar(data))

to_native_dtype 

to_native_dtype() -> UInt8DType

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

Returns:

  • UInt8DType –

    The NumPy unsigned 8-bit integer dtype.

Source code in zarr/core/dtype/npy/int.py 
425
426
427
428
429
430
431
432
433
434
435
def to_native_dtype(self: Self) -> np.dtypes.UInt8DType:
    """
    Create a NumPy unsigned 8-bit integer dtype instance from this UInt8 ZDType.

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

    return self.dtype_cls()

VariableLengthBytes dataclass

Bases: ZDType[ObjectDType, bytes], 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.

Source code in zarr/core/dtype/npy/bytes.py 
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
@dataclass(frozen=True, kw_only=True)
class VariableLengthBytes(ZDType[np.dtypes.ObjectDType, bytes], 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.
    """

    dtype_cls = np.dtypes.ObjectDType
    _zarr_v3_name: ClassVar[Literal["variable_length_bytes"]] = "variable_length_bytes"
    object_codec_id: ClassVar[Literal["vlen-bytes"]] = "vlen-bytes"

    @classmethod
    def from_native_dtype(cls, dtype: TBaseDType) -> Self:
        """
        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
        ----------
        dtype : TBaseDType
            The native dtype to convert.

        Returns
        -------
        VariableLengthBytes
            An instance of VariableLengthBytes.

        Raises
        ------
        DataTypeValidationError
            If the dtype is not compatible with VariableLengthBytes.
        """
        if cls._check_native_dtype(dtype):
            return cls()
        raise DataTypeValidationError(
            f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
        )

    def to_native_dtype(self) -> np.dtypes.ObjectDType:
        """
        Create a NumPy object dtype from this VariableLengthBytes ZDType.

        Returns
        -------
        np.dtypes.ObjectDType
            A NumPy data type object representing variable-length bytes.
        """
        return self.dtype_cls()

    @classmethod
    def _check_json_v2(
        cls,
        data: DTypeJSON,
    ) -> TypeGuard[VariableLengthBytesJSON_V2]:
        """
        Check that the input is a valid JSON representation of a NumPy O dtype, and that the
        object codec id is appropriate for variable-length bytes strings.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to check.

        Returns
        -------
        True if the input is a valid representation of this class in Zarr V2, False
        otherwise.
        """
        # Check that the input is a valid JSON representation of a Zarr v2 data type spec.
        if not check_dtype_spec_v2(data):
            return False

        # Check that the object codec id is appropriate for variable-length bytes strings.
        if data["name"] != "|O":
            return False
        return data["object_codec_id"] == cls.object_codec_id

    @classmethod
    def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[Literal["variable_length_bytes"]]:
        """
        Check that the input is a valid JSON representation of this class in Zarr V3.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to check.

        Returns
        -------
        TypeGuard[Literal["variable_length_bytes"]]
            True if the input is a valid representation of this class in Zarr V3, False otherwise.
        """

        return data == cls._zarr_v3_name

    @classmethod
    def _from_json_v2(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of this VariableLengthBytes from Zarr V2-flavored JSON.

        This method checks if the input data is a valid representation of this class
        in Zarr V2. If so, it returns a new instance this class.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to parse.

        Returns
        -------
        Self
            An instance of this data type.

        Raises
        ------
        DataTypeValidationError
            If the input data is not a valid representation of this class class.
        """

        if cls._check_json_v2(data):
            return cls()
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string '|O' and an object_codec_id of {cls.object_codec_id}"
        raise DataTypeValidationError(msg)

    @classmethod
    def _from_json_v3(cls, data: DTypeJSON) -> Self:
        """
        Create an instance of VariableLengthBytes from Zarr V3-flavored JSON.

        This method checks if the input data is a valid representation of
        VariableLengthBytes in Zarr V3. If so, it returns a new instance of
        VariableLengthBytes.

        Parameters
        ----------
        data : DTypeJSON
            The JSON data to parse.

        Returns
        -------
        VariableLengthBytes
            An instance of VariableLengthBytes.

        Raises
        ------
        DataTypeValidationError
            If the input data is not a valid representation of this class.
        """

        if cls._check_json_v3(data):
            return cls()
        msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
        raise DataTypeValidationError(msg)

    @overload
    def to_json(self, zarr_format: Literal[2]) -> VariableLengthBytesJSON_V2: ...

    @overload
    def to_json(self, zarr_format: Literal[3]) -> Literal["variable_length_bytes"]: ...

    def to_json(
        self, zarr_format: ZarrFormat
    ) -> VariableLengthBytesJSON_V2 | Literal["variable_length_bytes"]:
        """
        Convert the variable-length bytes data type to a JSON-serializable form.

        Parameters
        ----------
        zarr_format : ZarrFormat
            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.
        """

        if zarr_format == 2:
            return {"name": "|O", "object_codec_id": self.object_codec_id}
        elif zarr_format == 3:
            v3_unstable_dtype_warning(self)
            return self._zarr_v3_name
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    def default_scalar(self) -> bytes:
        """
        Return the default scalar value for the variable-length bytes data type.

        Returns
        -------
        bytes
            The default scalar value, which is an empty byte string.
        """

        return b""

    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
        """
        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
        ----------
        data : object
            The scalar to convert.
        zarr_format : ZarrFormat
            The zarr format version.

        Returns
        -------
        str
            A string representation of the scalar.
        """
        return base64.standard_b64encode(data).decode("ascii")  # type: ignore[arg-type]

    def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> bytes:
        """
        Decode a base64-encoded JSON string to bytes.

        Parameters
        ----------
        data : JSON
            The JSON-serializable base64-encoded string.
        zarr_format : ZarrFormat
            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.
        """

        if check_json_str(data):
            return base64.standard_b64decode(data.encode("ascii"))
        raise TypeError(f"Invalid type: {data}. Expected a string.")  # pragma: no cover

    def _check_scalar(self, data: object) -> TypeGuard[BytesLike]:
        """
        Check if the provided data is of type BytesLike.

        This method is used to verify if the input data can be considered as a
        scalar of bytes-like type, which includes NumPy bytes, strings, bytes,
        and integers.

        Parameters
        ----------
        data : object
            The data to check.

        Returns
        -------
        TypeGuard[BytesLike]
            True if the data is bytes-like, False otherwise.
        """
        return isinstance(data, BytesLike)

    def _cast_scalar_unchecked(self, data: BytesLike) -> bytes:
        """
        Cast the provided scalar data to bytes.

        Parameters
        ----------
        data : BytesLike
            The data to cast.

        Returns
        -------
        bytes
            The casted data as bytes.

        Notes
        -----
        This method does not perform any type checking.
        The input data must be bytes-like.
        """
        if isinstance(data, str):
            return bytes(data, encoding="utf-8")
        return bytes(data)

    def cast_scalar(self, data: object) -> bytes:
        """
        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
        ----------
        data : object
            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.
        """

        if self._check_scalar(data):
            return self._cast_scalar_unchecked(data)
        msg = (
            f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
            f"data type {self}."
        )
        raise TypeError(msg)

cast_scalar 

cast_scalar(data: object) -> bytes

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:

  • data (object) –

    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.

Source code in zarr/core/dtype/npy/bytes.py 
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
def cast_scalar(self, data: object) -> bytes:
    """
    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
    ----------
    data : object
        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.
    """

    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)

default_scalar 

default_scalar() -> bytes

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

Returns:

  • bytes –

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

Source code in zarr/core/dtype/npy/bytes.py 
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
def default_scalar(self) -> bytes:
    """
    Return the default scalar value for the variable-length bytes data type.

    Returns
    -------
    bytes
        The default scalar value, which is an empty byte string.
    """

    return b""

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> bytes

Decode a base64-encoded JSON string to bytes.

Parameters:

  • data (JSON) –

    The JSON-serializable base64-encoded string.

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/npy/bytes.py 
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> bytes:
    """
    Decode a base64-encoded JSON string to bytes.

    Parameters
    ----------
    data : JSON
        The JSON-serializable base64-encoded string.
    zarr_format : ZarrFormat
        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.
    """

    if check_json_str(data):
        return base64.standard_b64decode(data.encode("ascii"))
    raise TypeError(f"Invalid type: {data}. Expected a string.")  # pragma: no cover

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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:

  • dtype (TBaseDType) –

    The native dtype to convert.

Returns:

Raises:

  • DataTypeValidationError –

    If the dtype is not compatible with VariableLengthBytes.

Source code in zarr/core/dtype/npy/bytes.py 
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    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
    ----------
    dtype : TBaseDType
        The native dtype to convert.

    Returns
    -------
    VariableLengthBytes
        An instance of VariableLengthBytes.

    Raises
    ------
    DataTypeValidationError
        If the dtype is not compatible with VariableLengthBytes.
    """
    if cls._check_native_dtype(dtype):
        return cls()
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> VariableLengthBytesJSON_V2

to_json(
    zarr_format: Literal[3],
) -> Literal["variable_length_bytes"]

to_json(
    zarr_format: ZarrFormat,
) -> (
    VariableLengthBytesJSON_V2
    | Literal["variable_length_bytes"]
)

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

Parameters:

  • zarr_format (ZarrFormat) –

    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:

Source code in zarr/core/dtype/npy/bytes.py 
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
def to_json(
    self, zarr_format: ZarrFormat
) -> VariableLengthBytesJSON_V2 | Literal["variable_length_bytes"]:
    """
    Convert the variable-length bytes data type to a JSON-serializable form.

    Parameters
    ----------
    zarr_format : ZarrFormat
        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.
    """

    if zarr_format == 2:
        return {"name": "|O", "object_codec_id": self.object_codec_id}
    elif zarr_format == 3:
        v3_unstable_dtype_warning(self)
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> str

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:

  • data (object) –

    The scalar to convert.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • str –

    A string representation of the scalar.

Source code in zarr/core/dtype/npy/bytes.py 
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
    """
    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
    ----------
    data : object
        The scalar to convert.
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    str
        A string representation of the scalar.
    """
    return base64.standard_b64encode(data).decode("ascii")  # type: ignore[arg-type]

to_native_dtype 

to_native_dtype() -> ObjectDType

Create a NumPy object dtype from this VariableLengthBytes ZDType.

Returns:

  • ObjectDType –

    A NumPy data type object representing variable-length bytes.

Source code in zarr/core/dtype/npy/bytes.py 
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
def to_native_dtype(self) -> np.dtypes.ObjectDType:
    """
    Create a NumPy object dtype from this VariableLengthBytes ZDType.

    Returns
    -------
    np.dtypes.ObjectDType
        A NumPy data type object representing variable-length bytes.
    """
    return self.dtype_cls()

VariableLengthBytesJSON_V2

Bases: 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"
}
Source code in zarr/core/dtype/npy/bytes.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
class VariableLengthBytesJSON_V2(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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).

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

VariableLengthUTF8 dataclass

Bases: UTF8Base[ObjectDType]

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

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

Attributes:

  • dtype_cls (Type[ObjectDType]) –

    The NumPy dtype class for this data type.

  • _zarr_v3_name (ClassVar[Literal["variable_length_utf8"]] = "variable_length_utf8") –

    The name of this data type in Zarr V3.

  • object_codec_id (ClassVar[Literal["vlen-utf8"]] = "vlen-utf8") –

    The object codec ID for this data type.

Source code in zarr/core/dtype/npy/string.py 
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
@dataclass(frozen=True, kw_only=True)
class VariableLengthUTF8(UTF8Base[np.dtypes.ObjectDType]):  # type: ignore[no-redef]
    """
    A Zarr data type for arrays containing variable-length UTF-8 strings.

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


    Attributes
    ----------
    dtype_cls : Type[np.dtypes.ObjectDType]
        The NumPy dtype class for this data type.
    _zarr_v3_name : ClassVar[Literal["variable_length_utf8"]] = "variable_length_utf8"
        The name of this data type in Zarr V3.
    object_codec_id : ClassVar[Literal["vlen-utf8"]] = "vlen-utf8"
        The object codec ID for this data type.
    """

    dtype_cls = np.dtypes.ObjectDType

    def to_native_dtype(self) -> np.dtypes.ObjectDType:
        """
        Create a NumPy object dtype from this VariableLengthUTF8 ZDType.

        Returns
        -------
        np.dtypes.ObjectDType
            The NumPy object dtype.
        """
        return self.dtype_cls()

cast_scalar 

cast_scalar(data: object) -> str

Cast an object to a string.

Parameters:

  • data (object) –

    The value to cast.

Returns:

  • str –

    The input cast to str.

Source code in zarr/core/dtype/npy/string.py 
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
def cast_scalar(self, data: object) -> str:
    """
    Cast an object to a string.

    Parameters
    ----------
    data : object
        The value to cast.

    Returns
    -------
    str
        The input cast to str.
    """
    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    msg = (  # pragma: no cover
        f"Cannot convert object {data!r} with type {type(data)} to a scalar compatible with the "
        f"data type {self}."
    )
    raise TypeError(msg)  # pragma: no cover

default_scalar 

default_scalar() -> str

Return the default scalar value for this data type.

Returns:

  • str –

    The default scalar value.

Source code in zarr/core/dtype/npy/string.py 
615
616
617
618
619
620
621
622
623
624
def default_scalar(self) -> str:
    """
    Return the default scalar value for this data type.

    Returns
    -------
    str
        The default scalar value.
    """
    return ""

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> str

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

Parameters:

  • data (JSON) –

    The JSON representation of the scalar value.

  • zarr_format (int) –

    The zarr format to use for the JSON representation.

Returns:

  • str –

    The native scalar type of the scalar value.

Source code in zarr/core/dtype/npy/string.py 
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> str:
    """
    Convert a JSON representation of a scalar value to the native scalar type.

    Parameters
    ----------
    data : JSON
        The JSON representation of the scalar value.
    zarr_format : int
        The zarr format to use for the JSON representation.

    Returns
    -------
    str
        The native scalar type of the scalar value.
    """
    if not check_vlen_string_json_scalar(data):
        raise TypeError(f"Invalid type: {data}. Expected a string or number.")
    return str(data)

from_native_dtype classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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

Parameters:

  • dtype (TBaseDType) –

    The native data type.

Returns:

  • Self –

    An instance of this data type.

Raises:

  • DataTypeValidationError –

    If the input is not compatible with this data type.

Source code in zarr/core/dtype/npy/string.py 
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
@classmethod
def from_native_dtype(cls, dtype: TBaseDType) -> Self:
    """
    Create an instance of this data type from a compatible NumPy data type.


    Parameters
    ----------
    dtype : TBaseDType
        The native data type.

    Returns
    -------
    Self
        An instance of this data type.

    Raises
    ------
    DataTypeValidationError
        If the input is not compatible with this data type.
    """
    if cls._check_native_dtype(dtype):
        return cls()
    raise DataTypeValidationError(
        f"Invalid data type: {dtype}. Expected an instance of {cls.dtype_cls}"
    )

to_json 

to_json(
    zarr_format: Literal[2],
) -> VariableLengthUTF8JSON_V2

to_json(zarr_format: Literal[3]) -> Literal['string']

to_json(
    zarr_format: ZarrFormat,
) -> VariableLengthUTF8JSON_V2 | Literal["string"]

Convert this data type to a JSON representation.

Parameters:

  • zarr_format (int) –

    The zarr format to use for the JSON representation.

Returns:

  • ``VariableLengthUTF8JSON_V2 | Literal["string"]`` –

    The JSON representation of this data type.

Source code in zarr/core/dtype/npy/string.py 
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
def to_json(self, zarr_format: ZarrFormat) -> VariableLengthUTF8JSON_V2 | Literal["string"]:
    """
    Convert this data type to a JSON representation.

    Parameters
    ----------
    zarr_format : int
        The zarr format to use for the JSON representation.

    Returns
    -------
    ``VariableLengthUTF8JSON_V2 | Literal["string"]``
        The JSON representation of this data type.
    """
    if zarr_format == 2:
        return {"name": "|O", "object_codec_id": self.object_codec_id}
    elif zarr_format == 3:
        return self._zarr_v3_name
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

to_json_scalar 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> str

Convert a scalar value to a JSON representation.

Parameters:

  • data (object) –

    The scalar value to convert.

  • zarr_format (int) –

    The zarr format to use for the JSON representation.

Returns:

  • str –

    The JSON representation of the scalar value.

Source code in zarr/core/dtype/npy/string.py 
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> str:
    """
    Convert a scalar value to a JSON representation.

    Parameters
    ----------
    data : object
        The scalar value to convert.
    zarr_format : int
        The zarr format to use for the JSON representation.

    Returns
    -------
    str
        The JSON representation of the scalar value.
    """
    if self._check_scalar(data):
        return self._cast_scalar_unchecked(data)
    raise TypeError(f"Invalid type: {data}. Expected a string.")

to_native_dtype 

to_native_dtype() -> ObjectDType

Create a NumPy object dtype from this VariableLengthUTF8 ZDType.

Returns:

Source code in zarr/core/dtype/npy/string.py 
778
779
780
781
782
783
784
785
786
787
def to_native_dtype(self) -> np.dtypes.ObjectDType:
    """
    Create a NumPy object dtype from this VariableLengthUTF8 ZDType.

    Returns
    -------
    np.dtypes.ObjectDType
        The NumPy object dtype.
    """
    return self.dtype_cls()

VariableLengthUTF8JSON_V2

Bases: 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"
}
Source code in zarr/core/dtype/npy/string.py 
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
class VariableLengthUTF8JSON_V2(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](https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding).


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

ZDType dataclass

Bases: ABC, Generic[TDType_co, TScalar_co]

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

Attributes:

  • dtype_cls (ClassVar[type[TDType]]) –

    The wrapped dtype class. This is a class variable.

  • _zarr_v3_name (ClassVar[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.

Source code in zarr/core/dtype/wrapper.py 
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
@dataclass(frozen=True, kw_only=True, slots=True)
class ZDType(ABC, Generic[TDType_co, TScalar_co]):
    """
    Abstract base class for wrapping native array data types, e.g. numpy dtypes

    Attributes
    ----------
    dtype_cls : ClassVar[type[TDType]]
        The wrapped dtype class. This is a class variable.
    _zarr_v3_name : ClassVar[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.
    """

    # this class will create a native data type
    dtype_cls: ClassVar[type[TDType_co]]
    _zarr_v3_name: ClassVar[str]

    @classmethod
    def _check_native_dtype(cls: type[Self], dtype: TBaseDType) -> TypeGuard[TDType_co]:
        """
        Check that a native data type matches the dtype_cls class attribute.

        Used as a type guard.

        Parameters
        ----------
        dtype : TDType
            The dtype to check.

        Returns
        -------
        Bool
            True if the dtype matches, False otherwise.
        """
        return type(dtype) is cls.dtype_cls

    @classmethod
    @abstractmethod
    def from_native_dtype(cls: type[Self], dtype: TBaseDType) -> Self:
        """
        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
        ----------
        dtype : TDType
            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.
        """
        raise NotImplementedError  # pragma: no cover

    @abstractmethod
    def to_native_dtype(self: Self) -> TDType_co:
        """
        Return an instance of the wrapped data type. This operation inverts ``from_native_dtype``.

        Returns
        -------
        TDType
            The native data type wrapped by this ZDType.
        """
        raise NotImplementedError  # pragma: no cover

    @classmethod
    @abstractmethod
    def _from_json_v2(cls: type[Self], data: DTypeJSON) -> Self:
        raise NotImplementedError  # pragma: no cover

    @classmethod
    @abstractmethod
    def _from_json_v3(cls: type[Self], data: DTypeJSON) -> Self:
        raise NotImplementedError  # pragma: no cover

    @classmethod
    def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
        """
        Create an instance of this ZDType from JSON data.

        Parameters
        ----------
        data : DTypeJSON
            The JSON representation of the data type.

        zarr_format : ZarrFormat
            The zarr format version.

        Returns
        -------
        Self
            An instance of this data type.
        """
        if zarr_format == 2:
            return cls._from_json_v2(data)
        if zarr_format == 3:
            return cls._from_json_v3(data)
        raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

    @overload
    def to_json(self, zarr_format: Literal[2]) -> DTypeSpec_V2: ...

    @overload
    def to_json(self, zarr_format: Literal[3]) -> DTypeSpec_V3: ...

    @abstractmethod
    def to_json(self, zarr_format: ZarrFormat) -> DTypeSpec_V2 | DTypeSpec_V3:
        """
        Serialize this ZDType to JSON.

        Parameters
        ----------
        zarr_format : ZarrFormat
            The zarr format version.

        Returns
        -------
        DTypeJSON_V2 | DTypeJSON_V3
            The JSON-serializable representation of the wrapped data type
        """
        raise NotImplementedError  # pragma: no cover

    @abstractmethod
    def _check_scalar(self, data: object) -> bool:
        """
        Check that an python object is a valid scalar value for the wrapped data type.

        Parameters
        ----------
        data : object
            A value to check.

        Returns
        -------
        Bool
            True if the object is valid, False otherwise.
        """
        raise NotImplementedError  # pragma: no cover

    @abstractmethod
    def cast_scalar(self, data: object) -> TScalar_co:
        """
        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
        ----------
        data : object
            The python object to cast.

        Returns
        -------
        TScalar
            The cast value.
        """
        raise NotImplementedError  # pragma: no cover

    @abstractmethod
    def default_scalar(self) -> TScalar_co:
        """
        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.
        """
        raise NotImplementedError  # pragma: no cover

    @abstractmethod
    def from_json_scalar(self: Self, data: JSON, *, zarr_format: ZarrFormat) -> TScalar_co:
        """
        Read a JSON-serializable value as a scalar.

        Parameters
        ----------
        data : JSON
            A JSON representation of a scalar value.
        zarr_format : ZarrFormat
            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.
        """
        raise NotImplementedError  # pragma: no cover

    @abstractmethod
    def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> JSON:
        """
        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
        ----------
        data : object
            The value to convert.
        zarr_format : ZarrFormat
            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.
        """
        raise NotImplementedError  # pragma: no cover

cast_scalar abstractmethod 

cast_scalar(data: object) -> TScalar_co

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:

  • data (object) –

    The python object to cast.

Returns:

  • TScalar –

    The cast value.

Source code in zarr/core/dtype/wrapper.py 
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
@abstractmethod
def cast_scalar(self, data: object) -> TScalar_co:
    """
    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
    ----------
    data : object
        The python object to cast.

    Returns
    -------
    TScalar
        The cast value.
    """
    raise NotImplementedError  # pragma: no cover

default_scalar abstractmethod 

default_scalar() -> TScalar_co

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.

Source code in zarr/core/dtype/wrapper.py 
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
@abstractmethod
def default_scalar(self) -> TScalar_co:
    """
    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.
    """
    raise NotImplementedError  # pragma: no cover

from_json classmethod 

from_json(
    data: DTypeJSON, *, zarr_format: ZarrFormat
) -> Self

Create an instance of this ZDType from JSON data.

Parameters:

  • data (DTypeJSON) –

    The JSON representation of the data type.

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • Self –

    An instance of this data type.

Source code in zarr/core/dtype/wrapper.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
@classmethod
def from_json(cls: type[Self], data: DTypeJSON, *, zarr_format: ZarrFormat) -> Self:
    """
    Create an instance of this ZDType from JSON data.

    Parameters
    ----------
    data : DTypeJSON
        The JSON representation of the data type.

    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    Self
        An instance of this data type.
    """
    if zarr_format == 2:
        return cls._from_json_v2(data)
    if zarr_format == 3:
        return cls._from_json_v3(data)
    raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover

from_json_scalar abstractmethod 

from_json_scalar(
    data: JSON, *, zarr_format: ZarrFormat
) -> TScalar_co

Read a JSON-serializable value as a scalar.

Parameters:

  • data (JSON) –

    A JSON representation of a scalar value.

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/wrapper.py 
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
@abstractmethod
def from_json_scalar(self: Self, data: JSON, *, zarr_format: ZarrFormat) -> TScalar_co:
    """
    Read a JSON-serializable value as a scalar.

    Parameters
    ----------
    data : JSON
        A JSON representation of a scalar value.
    zarr_format : ZarrFormat
        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.
    """
    raise NotImplementedError  # pragma: no cover

from_native_dtype abstractmethod classmethod 

from_native_dtype(dtype: TBaseDType) -> Self

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:

  • dtype (TDType) –

    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.

Source code in zarr/core/dtype/wrapper.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
@classmethod
@abstractmethod
def from_native_dtype(cls: type[Self], dtype: TBaseDType) -> Self:
    """
    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
    ----------
    dtype : TDType
        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.
    """
    raise NotImplementedError  # pragma: no cover

to_json abstractmethod 

to_json(zarr_format: Literal[2]) -> DTypeSpec_V2

to_json(zarr_format: Literal[3]) -> DTypeSpec_V3

to_json(
    zarr_format: ZarrFormat,
) -> DTypeSpec_V2 | DTypeSpec_V3

Serialize this ZDType to JSON.

Parameters:

  • zarr_format (ZarrFormat) –

    The zarr format version.

Returns:

  • DTypeJSON_V2 | DTypeJSON_V3 –

    The JSON-serializable representation of the wrapped data type

Source code in zarr/core/dtype/wrapper.py 
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
@abstractmethod
def to_json(self, zarr_format: ZarrFormat) -> DTypeSpec_V2 | DTypeSpec_V3:
    """
    Serialize this ZDType to JSON.

    Parameters
    ----------
    zarr_format : ZarrFormat
        The zarr format version.

    Returns
    -------
    DTypeJSON_V2 | DTypeJSON_V3
        The JSON-serializable representation of the wrapped data type
    """
    raise NotImplementedError  # pragma: no cover

to_json_scalar abstractmethod 

to_json_scalar(
    data: object, *, zarr_format: ZarrFormat
) -> JSON

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:

  • data (object) –

    The value to convert.

  • zarr_format (ZarrFormat) –

    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.

Source code in zarr/core/dtype/wrapper.py 
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
@abstractmethod
def to_json_scalar(self, data: object, *, zarr_format: ZarrFormat) -> JSON:
    """
    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
    ----------
    data : object
        The value to convert.
    zarr_format : ZarrFormat
        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.
    """
    raise NotImplementedError  # pragma: no cover

to_native_dtype abstractmethod 

to_native_dtype() -> TDType_co

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

Returns:

  • TDType –

    The native data type wrapped by this ZDType.

Source code in zarr/core/dtype/wrapper.py 
122
123
124
125
126
127
128
129
130
131
132
@abstractmethod
def to_native_dtype(self: Self) -> TDType_co:
    """
    Return an instance of the wrapped data type. This operation inverts ``from_native_dtype``.

    Returns
    -------
    TDType
        The native data type wrapped by this ZDType.
    """
    raise NotImplementedError  # pragma: no cover

parse_dtype 

parse_dtype(
    dtype_spec: ZDTypeLike, *, zarr_format: ZarrFormat
) -> ZDType[TBaseDType, TBaseScalar]

Convert the input as a ZDType.

Parameters:

  • dtype_spec (ZDTypeLike) –

    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_format (ZarrFormat) –

    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')
Source code in zarr/core/dtype/__init__.py 
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
def parse_dtype(
    dtype_spec: ZDTypeLike,
    *,
    zarr_format: ZarrFormat,
) -> ZDType[TBaseDType, TBaseScalar]:
    """
    Convert the input as a ZDType.

    Parameters
    ----------
    dtype_spec : ZDTypeLike
        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_format : ZarrFormat
        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')
    """
    if isinstance(dtype_spec, ZDType):
        return dtype_spec
    # First attempt to interpret the input as JSON
    if isinstance(dtype_spec, Mapping | str | Sequence):
        try:
            return get_data_type_from_json(dtype_spec, zarr_format=zarr_format)  # type: ignore[arg-type]
        except ValueError:
            # no data type matched this JSON-like input
            pass
    if dtype_spec in VLEN_UTF8_ALIAS:
        # If the dtype request is one of the aliases for variable-length UTF-8 strings,
        # return that dtype.
        return VariableLengthUTF8()  # type: ignore[return-value]
    # otherwise, we have either a numpy dtype string, or a zarr v3 dtype string, and in either case
    # we can create a native dtype from it, and do the dtype inference from that
    return get_data_type_from_native_dtype(dtype_spec)  # type: ignore[arg-type]