docstrings

Author: d-v-b

docs/conf.py

@@ -56,7 +56,7 @@
 autoapi_member_order = "groupwise"
 autoapi_root = "api"
 autoapi_keep_files = True
-autoapi_options = [ 'members', 'undoc-members', 'show-inheritance', 'show-module-summary', 'imported-members', ]
+autoapi_options = [ 'members', 'undoc-members', 'show-inheritance', 'show-module-summary', 'imported-members', 'inherited-members']
 
 def skip_submodules(
         app: sphinx.application.Sphinx,
@@ -124,7 +124,7 @@ def skip_submodules(
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "talks"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "talks", "api"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

docs/user-guide/data_types.rst

@@ -151,17 +151,23 @@ class DataTypeValidationError(ValueError): ...
 class ScalarTypeValidationError(ValueError): ...
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class HasLength:
     """
     A mix-in class for data types with a length attribute, such as fixed-size collections
     of unicode strings, or bytes.
+
+    Attributes
+    ----------
+    length : int
+        The length of the scalars belonging to this data type. Note that this class does not assign
+        a unit to the length. Child classes may assign units.
     """
 
     length: int
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class HasEndianness:
     """
     A mix-in class for data types with an endianness attribute
@@ -170,7 +176,7 @@ class HasEndianness:
     endianness: EndiannessStr = "little"
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class HasItemSize:
     """
     A mix-in class for data types with an item size attribute.
@@ -183,7 +189,7 @@ def item_size(self) -> int:
         raise NotImplementedError
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, kw_only=True)
 class HasObjectCodec:
     """
     A mix-in class for data types that require an object codec id.

src/zarr/core/dtype/common.py

@@ -21,14 +21,23 @@
 @dataclass(frozen=True, kw_only=True, slots=True)
 class Bool(ZDType[np.dtypes.BoolDType, np.bool_], HasItemSize):
     """
-    Wrapper for numpy boolean dtype.
+    The boolean data type.
 
     Attributes
     ----------
-    name : str
-        The name of the dtype.
-    dtype_cls : ClassVar[type[np.dtypes.BoolDType]]
-        The numpy dtype class.
+    _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.
+
+    Notes
+    -----
+    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>`_
     """
 
     _zarr_v3_name: ClassVar[Literal["bool"]] = "bool"
@@ -38,7 +47,22 @@ class Bool(ZDType[np.dtypes.BoolDType, np.bool_], HasItemSize):
     @classmethod
     def from_native_dtype(cls, dtype: TBaseDType) -> Self:
         """
-        Create a Bool from a np.dtype('bool') instance.
+        Create an instance of Bool from an instance of np.dtypes.BoolDType.
+
+        Parameters
+        ----------
+        dtype : TBaseDType
+            The NumPy boolean dtype instance to convert.
+
+        Returns
+        -------
+        Bool
+            An instance of Bool.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the provided dtype is not compatible with this ZDType.
         """
         if cls._check_native_dtype(dtype):
             return cls()
@@ -48,7 +72,12 @@ def from_native_dtype(cls, dtype: TBaseDType) -> Self:
 
     def to_native_dtype(self: Self) -> np.dtypes.BoolDType:
         """
-        Create a NumPy boolean dtype instance from this ZDType
+        Create a NumPy boolean dtype instance from this ZDType.
+
+        Returns
+        -------
+        np.dtypes.BoolDType
+            The NumPy boolean dtype.
         """
         return self.dtype_cls()
 
@@ -59,6 +88,16 @@ def _check_json_v2(
     ) -> TypeGuard[DTypeConfig_V2[Literal["|b1"], None]]:
         """
         Check that the input is a valid JSON representation of a Bool.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        bool
+            True if the input is a valid JSON representation, False otherwise.
         """
         return (
             check_dtype_spec_v2(data)
@@ -68,17 +107,66 @@ 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.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data to check.
+
+        Returns
+        -------
+        bool
+            True if the input is a valid JSON representation, False otherwise.
+        """
         return data == cls._zarr_v3_name
 
     @classmethod
     def _from_json_v2(cls, data: DTypeJSON) -> Self:
+        """
+        Create an instance of Bool from Zarr V2-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Bool
+            An instance of Bool.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of a Bool.
+        """
         if cls._check_json_v2(data):
             return cls()
         msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v2_name!r}"
         raise DataTypeValidationError(msg)
 
     @classmethod
     def _from_json_v3(cls: type[Self], data: DTypeJSON) -> Self:
+        """
+        Create an instance of Bool from Zarr V3-flavored JSON.
+
+        Parameters
+        ----------
+        data : DTypeJSON
+            The JSON data.
+
+        Returns
+        -------
+        Bool
+            An instance of Bool.
+
+        Raises
+        ------
+        DataTypeValidationError
+            If the input JSON is not a valid representation of a Bool.
+        """
         if cls._check_json_v3(data):
             return cls()
         msg = f"Invalid JSON representation of {cls.__name__}. Got {data!r}, expected the string {cls._zarr_v3_name!r}"
@@ -93,17 +181,65 @@ def to_json(self, zarr_format: Literal[3]) -> Literal["bool"]: ...
     def to_json(
         self, zarr_format: ZarrFormat
     ) -> DTypeConfig_V2[Literal["|b1"], None] | Literal["bool"]:
+        """
+        Serialize this Bool instance to JSON.
+
+        Parameters
+        ----------
+        zarr_format : ZarrFormat
+            The Zarr format version (2 or 3).
+
+        Returns
+        -------
+        DTypeConfig_V2[Literal["|b1"], None] or Literal["bool"]
+            The JSON representation of the Bool instance.
+
+        Raises
+        ------
+        ValueError
+            If the zarr_format is not 2 or 3.
+        """
         if zarr_format == 2:
             return {"name": self._zarr_v2_name, "object_codec_id": None}
         elif zarr_format == 3:
             return self._zarr_v3_name
         raise ValueError(f"zarr_format must be 2 or 3, got {zarr_format}")  # pragma: no cover
 
     def _check_scalar(self, data: object) -> bool:
-        # Anything can become a bool
+        """
+        Check if the input can be cast to a boolean scalar.
+
+        Parameters
+        ----------
+        data : object
+            The data to check.
+
+        Returns
+        -------
+        bool
+            True if the input can be cast to a boolean scalar, False otherwise.
+        """
         return True
 
     def cast_scalar(self, data: object) -> np.bool_:
+        """
+        Cast the input to a numpy boolean scalar.
+
+        Parameters
+        ----------
+        data : object
+            The data to cast.
+
+        Returns
+        -------
+        np.bool_
+            The numpy boolean scalar.
+
+        Raises
+        ------
+        TypeError
+            If the input cannot be converted to a numpy boolean.
+        """
         if self._check_scalar(data):
             return np.bool_(data)
         msg = f"Cannot convert object with type {type(data)} to a numpy boolean."
@@ -153,11 +289,24 @@ def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> np.bool_:
         -------
         np.bool_
             The numpy boolean scalar.
+
+        Raises
+        ------
+        TypeError
+            If the input is not a valid boolean type.
         """
         if self._check_scalar(data):
             return np.bool_(data)
         raise TypeError(f"Invalid type: {data}. Expected a boolean.")  # pragma: no cover
 
     @property
     def item_size(self) -> int:
+        """
+        Return the item size of the boolean dtype.
+
+        Returns
+        -------
+        int
+            The item size in bytes.
+        """
         return 1