zarr.dtype
==========

.. py:module:: zarr.dtype


Attributes
----------

.. autoapisummary::

   zarr.dtype.data_type_registry


Exceptions
----------

.. autoapisummary::

   zarr.dtype.DataTypeValidationError


Classes
-------

.. autoapisummary::

   zarr.dtype.Bool
   zarr.dtype.Complex128
   zarr.dtype.Complex64
   zarr.dtype.DateTime64
   zarr.dtype.DateTime64JSON_V2
   zarr.dtype.DateTime64JSON_V3
   zarr.dtype.FixedLengthUTF32
   zarr.dtype.FixedLengthUTF32JSON_V2
   zarr.dtype.FixedLengthUTF32JSON_V3
   zarr.dtype.Float16
   zarr.dtype.Float32
   zarr.dtype.Float64
   zarr.dtype.Int16
   zarr.dtype.Int32
   zarr.dtype.Int64
   zarr.dtype.Int8
   zarr.dtype.NullTerminatedBytes
   zarr.dtype.NullTerminatedBytesJSON_V3
   zarr.dtype.NullterminatedBytesJSON_V2
   zarr.dtype.RawBytes
   zarr.dtype.RawBytesJSON_V2
   zarr.dtype.RawBytesJSON_V3
   zarr.dtype.Structured
   zarr.dtype.StructuredJSON_V2
   zarr.dtype.StructuredJSON_V3
   zarr.dtype.TimeDelta64
   zarr.dtype.TimeDelta64JSON_V2
   zarr.dtype.TimeDelta64JSON_V3
   zarr.dtype.UInt16
   zarr.dtype.UInt32
   zarr.dtype.UInt64
   zarr.dtype.UInt8
   zarr.dtype.VariableLengthBytes
   zarr.dtype.VariableLengthBytesJSON_V2
   zarr.dtype.VariableLengthUTF8
   zarr.dtype.VariableLengthUTF8JSON_V2
   zarr.dtype.ZDType


Functions
---------

.. autoapisummary::

   zarr.dtype.parse_dtype


Module Contents
---------------

.. py:exception:: DataTypeValidationError

   Bases: :py:obj:`ValueError`


   
   Inappropriate argument value (of correct type).
















   ..
       !! processed by numpydoc !!

.. py:class:: Bool

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


   
   A Zarr data type for arrays containing booleans.

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


   :Attributes:

       **_zarr_v3_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.











   .. rubric:: 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.

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: cast_scalar(data: object) -> numpy.bool_

      
      Cast the input to a numpy boolean scalar.


      :Parameters:

          **data** : object
              The data to cast.



      :Returns:

          ``np.bool_``
              The numpy boolean scalar.




      :Raises:

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







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> numpy.bool_

      
      Get the default value for the boolean dtype.





      :Returns:

          ``np.bool_``
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> numpy.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:

          ``np.bool_``
              The numpy boolean scalar.




      :Raises:

          TypeError
              If the input is not a valid boolean type.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['|b1'], None]
                  to_json(zarr_format: Literal[3]) -> 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.dtypes.BoolDType

      
      Create a NumPy boolean dtype instance from this ZDType.





      :Returns:

          np.dtypes.BoolDType
              The NumPy boolean dtype.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: Complex128

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


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

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


   :Attributes:

       **dtype_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.













   ..
       !! processed by numpydoc !!

   .. py:method:: cast_scalar(data: object) -> zarr.core.dtype.npy.common.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.







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> zarr.core.dtype.npy.common.TComplexScalar_co

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





      :Returns:

          Int scalar
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> zarr.core.dtype.npy.common.TComplexScalar_co

      
      Read a JSON-serializable value as a numpy float.


      :Parameters:

          **data** : JSON
              The JSON-serializable value.

          **zarr_format** : ZarrFormat
              The zarr format version.



      :Returns:

          TScalar_co
              The numpy float.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[str, None]
                  to_json(zarr_format: Literal[3]) -> str

      
      Serialize this object to a JSON-serializable representation.


      :Parameters:

          **zarr_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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> zarr.core.common.JSON

      
      Convert an object to a JSON-serializable float.


      :Parameters:

          **data** : _BaseScalar
              The value to convert.

          **zarr_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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> zarr.core.dtype.npy.common.TComplexDType_co

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





      :Returns:

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











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: Complex64

   Bases: :py:obj:`BaseComplex`\ [\ :py:obj:`numpy.dtypes.Complex64DType`\ , :py:obj:`numpy.complex64`\ ]


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

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


   :Attributes:

       **dtype_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.













   ..
       !! processed by numpydoc !!

   .. py:method:: cast_scalar(data: object) -> zarr.core.dtype.npy.common.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.







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> zarr.core.dtype.npy.common.TComplexScalar_co

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





      :Returns:

          Int scalar
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> zarr.core.dtype.npy.common.TComplexScalar_co

      
      Read a JSON-serializable value as a numpy float.


      :Parameters:

          **data** : JSON
              The JSON-serializable value.

          **zarr_format** : ZarrFormat
              The zarr format version.



      :Returns:

          TScalar_co
              The numpy float.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[str, None]
                  to_json(zarr_format: Literal[3]) -> str

      
      Serialize this object to a JSON-serializable representation.


      :Parameters:

          **zarr_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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> zarr.core.common.JSON

      
      Convert an object to a JSON-serializable float.


      :Parameters:

          **data** : _BaseScalar
              The value to convert.

          **zarr_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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> zarr.core.dtype.npy.common.TComplexDType_co

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





      :Returns:

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











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: DateTime64

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


   
   A Zarr data type for arrays containing NumPy Datetime64 data.

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


   :Attributes:

       **dtype_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.











   .. rubric:: 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>`__

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: cast_scalar(data: object) -> numpy.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.







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> numpy.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











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> numpy.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.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> DateTime64JSON_V2
                  to_json(zarr_format: Literal[3]) -> 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> int

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


      :Parameters:

          **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.











      ..
          !! processed by numpydoc !!


   .. py:method:: 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.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: scale_factor
      :type:  int
      :value: 1



   .. py:attribute:: unit
      :type:  zarr.core.dtype.npy.common.DateTimeUnit
      :value: 'generic'



.. py:class:: DateTime64JSON_V2

   Bases: :py:obj:`zarr.core.dtype.common.DTypeConfig_V2`\ [\ :py:obj:`str`\ , :py:obj:`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.













   .. rubric:: 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>`__.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

   .. py:attribute:: name
      :type:  typing_extensions.ReadOnly[TDTypeNameV2_co]


   .. py:attribute:: object_codec_id
      :type:  typing_extensions.ReadOnly[TObjectCodecID_co]


.. py:class:: DateTime64JSON_V3

   Bases: :py:obj:`zarr.core.common.NamedConfig`\ [\ :py:obj:`Literal`\ [\ :py:obj:`'numpy.datetime64'`\ ]\ , :py:obj:`TimeConfig`\ ]


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














   .. rubric:: References

   This representation is defined in the ``numpy.datetime64``
   `specification document <https://zarr-specs.readthedocs.io/en/latest/spec/v3/datatypes.html#numpy-datetime64>`__.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

   .. py:attribute:: configuration
      :type:  typing_extensions.ReadOnly[TConfig]

      
      The configuration of the object.
















      ..
          !! processed by numpydoc !!


   .. py:attribute:: name
      :type:  typing_extensions.ReadOnly[TName]

      
      The name of the object.
















      ..
          !! processed by numpydoc !!


.. py:class:: FixedLengthUTF32

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


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

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


   :Attributes:

       **dtype_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.













   ..
       !! processed by numpydoc !!

   .. py:method:: cast_scalar(data: object) -> numpy.str_

      
      Cast the scalar value to the native scalar value.


      :Parameters:

          **data** : object
              The scalar value.



      :Returns:

          ``np.str_``
              The native scalar value.











      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> numpy.str_

      
      Return the default scalar value for this data type.





      :Returns:

          ``np.str_``
              The default scalar value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> numpy.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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      Create a FixedLengthUTF32 from a NumPy data type.


      :Parameters:

          **dtype** : TBaseDType
              The NumPy data type.



      :Returns:

          Self
              An instance of this data type.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[str, None]
                  to_json(zarr_format: Literal[3]) -> 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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.dtypes.StrDType[int]

      
      Convert the FixedLengthUTF32 instance to a NumPy data type.





      :Returns:

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











      ..
          !! processed by numpydoc !!


   .. py:attribute:: code_point_bytes
      :type:  ClassVar[int]
      :value: 4



   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: length
      :type:  int


.. py:class:: FixedLengthUTF32JSON_V2

   Bases: :py:obj:`zarr.core.dtype.common.DTypeConfig_V2`\ [\ :py:obj:`str`\ , :py:obj:`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.













   .. rubric:: 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>`__.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

   .. py:attribute:: name
      :type:  typing_extensions.ReadOnly[TDTypeNameV2_co]


   .. py:attribute:: object_codec_id
      :type:  typing_extensions.ReadOnly[TObjectCodecID_co]


.. py:class:: FixedLengthUTF32JSON_V3

   Bases: :py:obj:`zarr.core.common.NamedConfig`\ [\ :py:obj:`Literal`\ [\ :py:obj:`'fixed_length_utf32'`\ ]\ , :py:obj:`LengthBytesConfig`\ ]


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














   .. rubric:: References

   This representation is not currently defined in an external specification.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

   .. py:attribute:: configuration
      :type:  typing_extensions.ReadOnly[TConfig]

      
      The configuration of the object.
















      ..
          !! processed by numpydoc !!


   .. py:attribute:: name
      :type:  typing_extensions.ReadOnly[TName]

      
      The name of the object.
















      ..
          !! processed by numpydoc !!


.. py:class:: Float16

   Bases: :py:obj:`BaseFloat`\ [\ :py:obj:`numpy.dtypes.Float16DType`\ , :py:obj:`numpy.float16`\ ]


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

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


   :Attributes:

       **dtype_cls** : Type[np.dtypes.Float16DType]
           The NumPy dtype class for this data type.











   .. rubric:: 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.

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: cast_scalar(data: object) -> zarr.core.dtype.npy.common.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.











      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> zarr.core.dtype.npy.common.TFloatScalar_co

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





      :Returns:

          TFloatScalar_co
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> zarr.core.dtype.npy.common.TFloatScalar_co

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


      :Parameters:

          **data** : JSON
              The JSON-serializable value.

          **zarr_format** : ZarrFormat
              The zarr format version.



      :Returns:

          TFloatScalar_co
              The NumPy float scalar.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[str, None]
                  to_json(zarr_format: Literal[3]) -> str

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


      :Parameters:

          **zarr_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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> float | str

      
      Convert an object to a JSON-serializable float.


      :Parameters:

          **data** : _BaseScalar
              The value to convert.

          **zarr_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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> zarr.core.dtype.npy.common.TFloatDType_co

      
      Convert the wrapped data type to a NumPy data type.





      :Returns:

          TFloatDType_co
              The NumPy data type.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: Float32

   Bases: :py:obj:`BaseFloat`\ [\ :py:obj:`numpy.dtypes.Float32DType`\ , :py:obj:`numpy.float32`\ ]


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

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


   :Attributes:

       **dtype_cls** : Type[np.dtypes.Float32DType]
           The NumPy dtype class for this data type.











   .. rubric:: 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.

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: cast_scalar(data: object) -> zarr.core.dtype.npy.common.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.











      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> zarr.core.dtype.npy.common.TFloatScalar_co

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





      :Returns:

          TFloatScalar_co
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> zarr.core.dtype.npy.common.TFloatScalar_co

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


      :Parameters:

          **data** : JSON
              The JSON-serializable value.

          **zarr_format** : ZarrFormat
              The zarr format version.



      :Returns:

          TFloatScalar_co
              The NumPy float scalar.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[str, None]
                  to_json(zarr_format: Literal[3]) -> str

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


      :Parameters:

          **zarr_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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> float | str

      
      Convert an object to a JSON-serializable float.


      :Parameters:

          **data** : _BaseScalar
              The value to convert.

          **zarr_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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> zarr.core.dtype.npy.common.TFloatDType_co

      
      Convert the wrapped data type to a NumPy data type.





      :Returns:

          TFloatDType_co
              The NumPy data type.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: Float64

   Bases: :py:obj:`BaseFloat`\ [\ :py:obj:`numpy.dtypes.Float64DType`\ , :py:obj:`numpy.float64`\ ]


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

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


   :Attributes:

       **dtype_cls** : Type[np.dtypes.Float64DType]
           The NumPy dtype class for this data type.











   .. rubric:: 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.

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: cast_scalar(data: object) -> zarr.core.dtype.npy.common.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.











      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> zarr.core.dtype.npy.common.TFloatScalar_co

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





      :Returns:

          TFloatScalar_co
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> zarr.core.dtype.npy.common.TFloatScalar_co

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


      :Parameters:

          **data** : JSON
              The JSON-serializable value.

          **zarr_format** : ZarrFormat
              The zarr format version.



      :Returns:

          TFloatScalar_co
              The NumPy float scalar.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[str, None]
                  to_json(zarr_format: Literal[3]) -> str

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


      :Parameters:

          **zarr_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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> float | str

      
      Convert an object to a JSON-serializable float.


      :Parameters:

          **data** : _BaseScalar
              The value to convert.

          **zarr_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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> zarr.core.dtype.npy.common.TFloatDType_co

      
      Convert the wrapped data type to a NumPy data type.





      :Returns:

          TFloatDType_co
              The NumPy data type.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: Int16

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


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

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


   :Attributes:

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











   .. rubric:: 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.

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> TIntScalar_co

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





      :Returns:

          TIntScalar_co
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> TIntScalar_co

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


      :Parameters:

          **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.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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').







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['>i2', '<i2'], None]
                  to_json(zarr_format: Literal[3]) -> 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> int

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


      :Parameters:

          **data** : object
              The value to convert.

          **zarr_format** : ZarrFormat
              The Zarr format version.



      :Returns:

          int
              The JSON-serializable form of the scalar.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.dtypes.Int16DType

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





      :Returns:

          np.dtype
              The np.dtype('int16') instance.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: Int32

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


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

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


   :Attributes:

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











   .. rubric:: 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.

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> TIntScalar_co

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





      :Returns:

          TIntScalar_co
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> TIntScalar_co

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


      :Parameters:

          **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.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['>i4', '<i4'], None]
                  to_json(zarr_format: Literal[3]) -> 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> int

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


      :Parameters:

          **data** : object
              The value to convert.

          **zarr_format** : ZarrFormat
              The Zarr format version.



      :Returns:

          int
              The JSON-serializable form of the scalar.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.dtypes.Int32DType

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





      :Returns:

          np.dtypes.Int32DType
              The np.dtype('int32') instance.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: Int64

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


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

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


   :Attributes:

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











   .. rubric:: 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.

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> TIntScalar_co

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





      :Returns:

          TIntScalar_co
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> TIntScalar_co

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


      :Parameters:

          **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.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['>i8', '<i8'], None]
                  to_json(zarr_format: Literal[3]) -> 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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> int

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


      :Parameters:

          **data** : object
              The value to convert.

          **zarr_format** : ZarrFormat
              The Zarr format version.



      :Returns:

          int
              The JSON-serializable form of the scalar.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.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.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: Int8

   Bases: :py:obj:`BaseInt`\ [\ :py:obj:`numpy.dtypes.Int8DType`\ , :py:obj:`numpy.int8`\ ]


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

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


   :Attributes:

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











   .. rubric:: 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.

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> TIntScalar_co

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





      :Returns:

          TIntScalar_co
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> TIntScalar_co

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


      :Parameters:

          **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.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['|i1'], None]
                  to_json(zarr_format: Literal[3]) -> 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> int

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


      :Parameters:

          **data** : object
              The value to convert.

          **zarr_format** : ZarrFormat
              The Zarr format version.



      :Returns:

          int
              The JSON-serializable form of the scalar.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.dtypes.Int8DType

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





      :Returns:

          np.dtypes.Int8DType
              The np.dtype('int8') instance.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: NullTerminatedBytes

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


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

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

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


   :Attributes:

       **dtype_cls: ClassVar[type[np.dtypes.BytesDType[int]]] = np.dtypes.BytesDType**
           The NumPy data type wrapped by this ZDType.

       **_zarr_v3_name** : ClassVar[Literal["null_terminated_bytes"]]
           ..

       **length** : int
           The length of the bytes.










   .. rubric:: 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.



   ..
       !! processed by numpydoc !!

   .. py:method:: cast_scalar(data: object) -> numpy.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:

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




      :Raises:

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







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> numpy.bytes_

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





      :Returns:

          ``np.bytes_``
              The default scalar value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> numpy.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:

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




      :Raises:

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







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> NullterminatedBytesJSON_V2
                  to_json(zarr_format: Literal[3]) -> 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











      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.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.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: length
      :type:  int


.. py:class:: NullTerminatedBytesJSON_V3

   Bases: :py:obj:`zarr.core.common.NamedConfig`\ [\ :py:obj:`Literal`\ [\ :py:obj:`'null_terminated_bytes'`\ ]\ , :py:obj:`FixedLengthBytesConfig`\ ]


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














   .. rubric:: References

   This representation is not currently defined in an external specification.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

.. py:class:: NullterminatedBytesJSON_V2

   Bases: :py:obj:`zarr.core.dtype.common.DTypeConfig_V2`\ [\ :py:obj:`str`\ , :py:obj:`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.













   .. rubric:: 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>`__.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

.. py:class:: RawBytes

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


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

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

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


   :Attributes:

       **dtype_cls: ClassVar[type[np.dtypes.VoidDType[int]]] = np.dtypes.VoidDtype**
           The NumPy data type wrapped by this ZDType.

       **_zarr_v3_name** : ClassVar[Literal["raw_bytes"]]
           ..

       **length** : int
           The length of the bytes.










   .. rubric:: 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.



   ..
       !! processed by numpydoc !!

   .. py:method:: cast_scalar(data: object) -> numpy.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.







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> numpy.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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> numpy.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.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> RawBytesJSON_V2
                  to_json(zarr_format: Literal[3]) -> 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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.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.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: length
      :type:  int


.. py:class:: RawBytesJSON_V2

   Bases: :py:obj:`zarr.core.dtype.common.DTypeConfig_V2`\ [\ :py:obj:`str`\ , :py:obj:`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.













   .. rubric:: 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>`__.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

   .. py:attribute:: name
      :type:  typing_extensions.ReadOnly[TDTypeNameV2_co]


   .. py:attribute:: object_codec_id
      :type:  typing_extensions.ReadOnly[TObjectCodecID_co]


.. py:class:: RawBytesJSON_V3

   Bases: :py:obj:`zarr.core.common.NamedConfig`\ [\ :py:obj:`Literal`\ [\ :py:obj:`'raw_bytes'`\ ]\ , :py:obj:`FixedLengthBytesConfig`\ ]


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














   .. rubric:: References

   This representation is not currently defined in an external specification.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

   .. py:attribute:: configuration
      :type:  typing_extensions.ReadOnly[TConfig]

      
      The configuration of the object.
















      ..
          !! processed by numpydoc !!


   .. py:attribute:: name
      :type:  typing_extensions.ReadOnly[TName]

      
      The name of the object.
















      ..
          !! processed by numpydoc !!


.. py:class:: Structured

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


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

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


   :Attributes:

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











   .. rubric:: 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>`__.

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: cast_scalar(data: object) -> numpy.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.







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> numpy.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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> numpy.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.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.




      .. rubric:: Notes

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



      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> StructuredJSON_V2
                  to_json(zarr_format: Literal[3]) -> 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.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.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


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


   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: StructuredJSON_V2

   Bases: :py:obj:`zarr.core.dtype.common.DTypeConfig_V2`\ [\ :py:obj:`zarr.core.dtype.common.StructuredName_V2`\ , :py:obj:`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.













   .. rubric:: 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>`__.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

.. py:class:: StructuredJSON_V3

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


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














   .. rubric:: References

   This representation is not currently defined in an external specification.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

   .. py:attribute:: configuration
      :type:  typing_extensions.ReadOnly[TConfig]

      
      The configuration of the object.
















      ..
          !! processed by numpydoc !!


   .. py:attribute:: name
      :type:  typing_extensions.ReadOnly[TName]

      
      The name of the object.
















      ..
          !! processed by numpydoc !!


.. py:class:: TimeDelta64

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


   
   A Zarr data type for arrays containing NumPy TimeDelta64 data.

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


   :Attributes:

       **dtype_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.











   .. rubric:: 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>`__

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: cast_scalar(data: object) -> numpy.timedelta64

      
      Cast the input to a numpy timedelta64 scalar. If the input is not a scalar of this data type,
      raise a TypeError.
















      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> numpy.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.















      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> numpy.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.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> TimeDelta64JSON_V2
                  to_json(zarr_format: Literal[3]) -> 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> int

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


      :Parameters:

          **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.











      ..
          !! processed by numpydoc !!


   .. py:method:: 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.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: scale_factor
      :type:  int
      :value: 1



   .. py:attribute:: unit
      :type:  zarr.core.dtype.npy.common.DateTimeUnit
      :value: 'generic'



.. py:class:: TimeDelta64JSON_V2

   Bases: :py:obj:`zarr.core.dtype.common.DTypeConfig_V2`\ [\ :py:obj:`str`\ , :py:obj:`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.













   .. rubric:: 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>`__.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

   .. py:attribute:: name
      :type:  typing_extensions.ReadOnly[TDTypeNameV2_co]


   .. py:attribute:: object_codec_id
      :type:  typing_extensions.ReadOnly[TObjectCodecID_co]


.. py:class:: TimeDelta64JSON_V3

   Bases: :py:obj:`zarr.core.common.NamedConfig`\ [\ :py:obj:`Literal`\ [\ :py:obj:`'numpy.timedelta64'`\ ]\ , :py:obj:`TimeConfig`\ ]


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














   .. rubric:: References

   This representation is defined in the numpy.timedelta64
   `specification document <https://zarr-specs.readthedocs.io/en/latest/spec/v3/datatypes.html#numpy-timedelta64>`__.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

   .. py:attribute:: configuration
      :type:  typing_extensions.ReadOnly[TConfig]

      
      The configuration of the object.
















      ..
          !! processed by numpydoc !!


   .. py:attribute:: name
      :type:  typing_extensions.ReadOnly[TName]

      
      The name of the object.
















      ..
          !! processed by numpydoc !!


.. py:class:: UInt16

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


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

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


   :Attributes:

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











   .. rubric:: 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.

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> TIntScalar_co

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





      :Returns:

          TIntScalar_co
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> TIntScalar_co

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


      :Parameters:

          **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.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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').







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['>u2', '<u2'], None]
                  to_json(zarr_format: Literal[3]) -> 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> int

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


      :Parameters:

          **data** : object
              The value to convert.

          **zarr_format** : ZarrFormat
              The Zarr format version.



      :Returns:

          int
              The JSON-serializable form of the scalar.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.dtypes.UInt16DType

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





      :Returns:

          np.dtype
              The np.dtype('uint16') instance.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: UInt32

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


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

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


   :Attributes:

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











   .. rubric:: 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.

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> TIntScalar_co

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





      :Returns:

          TIntScalar_co
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> TIntScalar_co

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


      :Parameters:

          **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.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['>u4', '<u4'], None]
                  to_json(zarr_format: Literal[3]) -> 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











      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> int

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


      :Parameters:

          **data** : object
              The value to convert.

          **zarr_format** : ZarrFormat
              The Zarr format version.



      :Returns:

          int
              The JSON-serializable form of the scalar.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.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.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: UInt64

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


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

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


   :Attributes:

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











   .. rubric:: 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.

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> TIntScalar_co

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





      :Returns:

          TIntScalar_co
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> TIntScalar_co

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


      :Parameters:

          **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.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['>u8', '<u8'], None]
                  to_json(zarr_format: Literal[3]) -> 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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> int

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


      :Parameters:

          **data** : object
              The value to convert.

          **zarr_format** : ZarrFormat
              The Zarr format version.



      :Returns:

          int
              The JSON-serializable form of the scalar.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.dtypes.UInt64DType

      
      Convert the data type to a native NumPy dtype.





      :Returns:

          np.dtypes.UInt64DType
              The native NumPy dtype.eeeeeeeeeeeeeeeee











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: endianness
      :type:  EndiannessStr
      :value: 'little'



   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: UInt8

   Bases: :py:obj:`BaseInt`\ [\ :py:obj:`numpy.dtypes.UInt8DType`\ , :py:obj:`numpy.uint8`\ ]


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

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


   :Attributes:

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











   .. rubric:: 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.

   .. only:: latex

      


   ..
       !! processed by numpydoc !!

   .. py:method:: 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> TIntScalar_co

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





      :Returns:

          TIntScalar_co
              The default value.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> TIntScalar_co

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


      :Parameters:

          **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.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      Create a UInt8 from a np.dtype('uint8') instance.
















      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeConfig_V2[Literal['|u1'], None]
                  to_json(zarr_format: Literal[3]) -> 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> int

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


      :Parameters:

          **data** : object
              The value to convert.

          **zarr_format** : ZarrFormat
              The Zarr format version.



      :Returns:

          int
              The JSON-serializable form of the scalar.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.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.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:property:: item_size
      :type: int


      
      The size of a single scalar in bytes.





      :Returns:

          int
              The size of a single scalar in bytes.











      ..
          !! processed by numpydoc !!


.. py:class:: VariableLengthBytes

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


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

   Wraps the NumPy "object" data type. Scalars for this data type are instances of ``bytes``.


   :Attributes:

       **dtype_cls: ClassVar[type[np.dtypes.ObjectDType]] = np.dtypes.ObjectDType**
           The NumPy data type wrapped by this ZDType.

       **_zarr_v3_name: ClassVar[Literal["variable_length_bytes"]] = "variable_length_bytes"**
           The name of this data type in Zarr V3.

       **object_codec_id: ClassVar[Literal["vlen-bytes"]] = "vlen-bytes"**
           The object codec ID for this data type.










   .. rubric:: 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.



   ..
       !! processed by numpydoc !!

   .. py:method:: 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: 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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.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.







      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) -> Self
      :classmethod:


      
      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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> VariableLengthBytesJSON_V2
                  to_json(zarr_format: Literal[3]) -> 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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> numpy.dtypes.ObjectDType

      
      Create a NumPy object dtype from this VariableLengthBytes ZDType.





      :Returns:

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











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


   .. py:attribute:: object_codec_id
      :type:  ClassVar[Literal['vlen-bytes']]
      :value: 'vlen-bytes'



.. py:class:: VariableLengthBytesJSON_V2

   Bases: :py:obj:`zarr.core.dtype.common.DTypeConfig_V2`\ [\ :py:obj:`Literal`\ [\ :py:obj:`'|O'`\ ]\ , :py:obj:`Literal`\ [\ :py:obj:`'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"``













   .. rubric:: 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>`__.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

   .. py:attribute:: name
      :type:  typing_extensions.ReadOnly[TDTypeNameV2_co]


   .. py:attribute:: object_codec_id
      :type:  typing_extensions.ReadOnly[TObjectCodecID_co]


.. py:class:: VariableLengthUTF8

   Bases: :py:obj:`UTF8Base`\ [\ :py:obj:`numpy.dtypes.StringDType`\ ]


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

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


   :Attributes:

       **dtype_cls** : Type[np.dtypes.StringDType]
           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.













   ..
       !! processed by numpydoc !!

   .. py:method:: to_native_dtype() -> numpy.dtypes.StringDType

      
      Create a NumPy string dtype from this VariableLengthUTF8 ZDType.





      :Returns:

          np.dtypes.StringDType
              The NumPy string dtype.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls


.. py:class:: VariableLengthUTF8JSON_V2

   Bases: :py:obj:`zarr.core.dtype.common.DTypeConfig_V2`\ [\ :py:obj:`Literal`\ [\ :py:obj:`'|O'`\ ]\ , :py:obj:`Literal`\ [\ :py:obj:`'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"``.













   .. rubric:: 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>`__.

   .. only:: latex

      

   .. rubric:: Examples

   .. code-block:: python

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

   ..
       !! processed by numpydoc !!

   .. py:attribute:: name
      :type:  typing_extensions.ReadOnly[TDTypeNameV2_co]


   .. py:attribute:: object_codec_id
      :type:  typing_extensions.ReadOnly[TObjectCodecID_co]


.. py:class:: ZDType

   Bases: :py:obj:`abc.ABC`, :py:obj:`Generic`\ [\ :py:obj:`TDType_co`\ , :py:obj:`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.













   ..
       !! processed by numpydoc !!

   .. py:method:: cast_scalar(data: object) -> TScalar_co
      :abstractmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: default_scalar() -> TScalar_co
      :abstractmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json(data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat) -> Self
      :classmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_json_scalar(data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat) -> TScalar_co
      :abstractmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: from_native_dtype(dtype: TBaseDType) -> Self
      :classmethod:

      :abstractmethod:


      
      Create a ZDType instance from a native data type.

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

      :Parameters:

          **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.







      ..
          !! processed by numpydoc !!


   .. py:method:: to_json(zarr_format: Literal[2]) -> zarr.core.dtype.common.DTypeSpec_V2
                  to_json(zarr_format: Literal[3]) -> zarr.core.dtype.common.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











      ..
          !! processed by numpydoc !!


   .. py:method:: to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) -> zarr.core.common.JSON
      :abstractmethod:


      
      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.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_native_dtype() -> TDType_co
      :abstractmethod:


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





      :Returns:

          TDType
              The native data type wrapped by this ZDType.











      ..
          !! processed by numpydoc !!


   .. py:attribute:: dtype_cls
      :type:  ClassVar[type[TDType_co]]


.. py:function:: parse_dtype(dtype_spec: ZDTypeLike, *, zarr_format: zarr.core.common.ZarrFormat) -> wrapper.ZDType[wrapper.TBaseDType, wrapper.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.










   .. rubric:: 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')

   ..
       !! processed by numpydoc !!

.. py:data:: data_type_registry

