document and export typeddicts, move dtype docs to an advanced section

Author: d-v-b

docs/user-guide/arrays.rst

@@ -23,7 +23,8 @@ The code above creates a 2-dimensional array of 32-bit integers with 10000 rows
 and 10000 columns, divided into chunks where each chunk has 1000 rows and 1000
 columns (and so there will be 100 chunks in total). The data is written to a
 :class:`zarr.storage.MemoryStore` (e.g. an in-memory dict). See
-:ref:`user-guide-persist` for details on storing arrays in other stores.
+:ref:`user-guide-persist` for details on storing arrays in other stores, and see
+:ref:`user-guide-data-types` for an in-depth look at the data types supported by Zarr.
 
 For a complete list of array creation routines see the :mod:`zarr`
 module documentation.

docs/user-guide/data_types.rst

@@ -1,3 +1,5 @@
+.. _user-guide-data-types:
+
 Array data types
 ================
 

docs/user-guide/index.rst

@@ -8,7 +8,6 @@ User guide
 
     installation
     arrays
-    data_types
     groups
     attributes
     storage
@@ -21,6 +20,7 @@ Advanced Topics
 .. toctree::
     :maxdepth: 1
 
+    data_types
     performance
     consolidated_metadata
     extending

src/zarr/core/dtype/__init__.py

@@ -7,14 +7,28 @@
     DTypeJSON,
 )
 from zarr.core.dtype.npy.bool import Bool
-from zarr.core.dtype.npy.bytes import NullTerminatedBytes, RawBytes, VariableLengthBytes
+from zarr.core.dtype.npy.bytes import (
+    NullTerminatedBytes,
+    NullterminatedBytesJSON_V2,
+    NullTerminatedBytesJSON_V3,
+    RawBytes,
+    RawBytesJSON_V2,
+    RawBytesJSON_V3,
+    VariableLengthBytes,
+    VariableLengthBytesJSON_V2,
+)
 from zarr.core.dtype.npy.complex import Complex64, Complex128
 from zarr.core.dtype.npy.float import Float16, Float32, Float64
 from zarr.core.dtype.npy.int import Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64
-from zarr.core.dtype.npy.structured import (
-    Structured,
+from zarr.core.dtype.npy.structured import Structured, StructuredJSON_V2, StructuredJSON_V3
+from zarr.core.dtype.npy.time import (
+    DateTime64,
+    DateTime64JSON_V2,
+    DateTime64JSON_V3,
+    TimeDelta64,
+    TimeDelta64JSON_V2,
+    TimeDelta64JSON_V3,
 )
-from zarr.core.dtype.npy.time import DateTime64, TimeDelta64
 
 if TYPE_CHECKING:
     from zarr.core.common import ZarrFormat
@@ -27,7 +41,10 @@
 from zarr.core.common import JSON
 from zarr.core.dtype.npy.string import (
     FixedLengthUTF32,
+    FixedLengthUTF32JSON_V2,
+    FixedLengthUTF32JSON_V3,
     VariableLengthUTF8,
+    VariableLengthUTF8JSON_V2,
 )
 from zarr.core.dtype.registry import DataTypeRegistry
 from zarr.core.dtype.wrapper import TBaseDType, TBaseScalar, ZDType
@@ -39,7 +56,11 @@
     "DataTypeRegistry",
     "DataTypeValidationError",
     "DateTime64",
+    "DateTime64JSON_V2",
+    "DateTime64JSON_V3",
     "FixedLengthUTF32",
+    "FixedLengthUTF32JSON_V2",
+    "FixedLengthUTF32JSON_V3",
     "Float16",
     "Float32",
     "Float64",
@@ -48,18 +69,28 @@
     "Int32",
     "Int64",
     "NullTerminatedBytes",
+    "NullTerminatedBytesJSON_V3",
+    "NullterminatedBytesJSON_V2",
     "RawBytes",
+    "RawBytesJSON_V2",
+    "RawBytesJSON_V3",
     "Structured",
+    "StructuredJSON_V2",
+    "StructuredJSON_V3",
     "TBaseDType",
     "TBaseScalar",
     "TimeDelta64",
     "TimeDelta64",
+    "TimeDelta64JSON_V2",
+    "TimeDelta64JSON_V3",
     "UInt8",
     "UInt16",
     "UInt32",
     "UInt64",
     "VariableLengthBytes",
+    "VariableLengthBytesJSON_V2",
     "VariableLengthUTF8",
+    "VariableLengthUTF8JSON_V2",
     "ZDType",
     "data_type_registry",
     "parse_data_type",

src/zarr/core/dtype/npy/bool.py

@@ -37,11 +37,11 @@ class Bool(ZDType[np.dtypes.BoolDType, np.bool_], HasItemSize):
     dtype_cls : ClassVar[type[np.dtypes.BoolDType]] = np.dtypes.BoolDType
         The NumPy dtype class.
 
-    Notes
-    -----
+    References
+    ----------
     This class implements the boolean data type defined in Zarr V2 and V3.
-    You can read the formal specification of that data type in the respective
-    `specification document <https://zarr-specs.readthedocs.io/en/latest/specs.html>`_
+
+    See the `Zarr V2 <https://github.com/zarr-developers/zarr-specs/blob/main/docs/v2/v2.0.rst#data-type-encoding>`_ and `Zarr V3 <https://github.com/zarr-developers/zarr-specs/blob/main/docs/v3/data-types/index.rst>`_ specification documents for details.
     """
 
     _zarr_v3_name: ClassVar[Literal["bool"]] = "bool"
@@ -112,7 +112,7 @@ def _check_json_v2(
     @classmethod
     def _check_json_v3(cls, data: DTypeJSON) -> TypeGuard[Literal["bool"]]:
         """
-        Check that the input is a valid JSON representation of a Bool in Zarr V3 format.
+        Check that the input is a valid JSON representation of this class in Zarr V3.
 
         Parameters
         ----------
@@ -144,7 +144,7 @@ def _from_json_v2(cls, data: DTypeJSON) -> Self:
         Raises
         ------
         DataTypeValidationError
-            If the input JSON is not a valid representation of a Bool.
+            If the input JSON is not a valid representation of this class.
         """
         if cls._check_json_v2(data):
             return cls()
@@ -169,7 +169,7 @@ def _from_json_v3(cls: type[Self], data: DTypeJSON) -> Self:
         Raises
         ------
         DataTypeValidationError
-            If the input JSON is not a valid representation of a Bool.
+            If the input JSON is not a valid representation of this class.
         """
         if cls._check_json_v3(data):
             return cls()