special type for array.chunks

Author: jhamman

.pre-commit-config.yaml

@@ -4,9 +4,13 @@ ci:
   autofix_commit_msg: "style: pre-commit fixes"
   autofix_prs: false
 default_stages: [pre-commit, pre-push]
+
+default_language_version:
+  python: python3.11
+
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.3
+    rev: v0.14.10
     hooks:
       - id: ruff-check
         args: ["--fix", "--show-fixes"]
@@ -23,7 +27,7 @@ repos:
         exclude: mkdocs.yml
       - id: trailing-whitespace
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.18.2
+    rev: v1.19.1
     hooks:
       - id: mypy
         files: src|tests
@@ -42,7 +46,7 @@ repos:
           - hypothesis
           - s3fs
   - repo: https://github.com/scientific-python/cookie
-    rev: 2025.10.20
+    rev: 2025.11.21
     hooks:
       - id: sp-repo-review
   - repo: https://github.com/pre-commit/pygrep-hooks
@@ -51,7 +55,7 @@ repos:
       - id: rst-directive-colons
       - id: rst-inline-touching-normal
   - repo: https://github.com/numpy/numpydoc
-    rev: v1.9.0
+    rev: v1.10.0
     hooks:
       - id: numpydoc-validation
   - repo: https://github.com/twisted/towncrier

pyproject.toml

@@ -395,6 +395,7 @@ ignore_errors = true
 minversion = "7"
 testpaths = ["tests", "docs/user-guide"]
 log_cli_level = "INFO"
+log_level = "INFO"
 xfail_strict = true
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"

src/zarr/_cli/cli.py

@@ -35,7 +35,7 @@ class CLIZarrFormatV3(str, Enum):
     v3 = "v3"
 
 
-@app.command()  # type: ignore[misc]
+@app.command()  # type: ignore[untyped-decorator]
 def migrate(
     zarr_format: Annotated[
         CLIZarrFormatV3,
@@ -120,7 +120,7 @@ def migrate(
         sync(migrate_metadata.remove_metadata(write_store, 2, force=False, dry_run=dry_run))
 
 
-@app.command()  # type: ignore[misc]
+@app.command()  # type: ignore[untyped-decorator]
 def remove_metadata(
     zarr_format: Annotated[
         CLIZarrFormat,
@@ -168,7 +168,7 @@ def remove_metadata(
     )
 
 
-@app.callback()  # type: ignore[misc]
+@app.callback()  # type: ignore[untyped-decorator]
 def main(
     verbose: Annotated[
         bool,

src/zarr/core/array.py

@@ -1300,6 +1300,8 @@ def _shard_grid_shape(self) -> tuple[int, ...]:
         """
         The shape of the shard grid for this array.
 
+        When no shards are present this will automatically fall back to the chunk grid.
+
         Returns
         -------
         tuple[int, ...]
@@ -1331,10 +1333,12 @@ def _nshards(self) -> int:
         """
         The number of shards in this array.
 
+        If no shards are present this will fall back to giving the number of chunks
+
         Returns
         -------
         int
-            The total number of shards in the array.
+            The total number of shards or if absent, chunks in the array.
         """
         return product(self._shard_grid_shape)
 
@@ -1464,6 +1468,8 @@ def _iter_shard_coords(
         """
         Create an iterator over the coordinates of shards in shard grid space.
 
+        This will fall back to chunk grid space in case no shards are present.
+
         Note that
 
         If the `origin` keyword is used, iteration will start at the shard index specified by `origin`.
@@ -1482,7 +1488,7 @@ def _iter_shard_coords(
         Yields
         ------
         chunk_coords: tuple[int, ...]
-            The coordinates of each shard in the selection.
+            The coordinates of each shard in the selection or chunk in case of no shard being present.
         """
         return _iter_shard_coords(
             array=self,
@@ -1496,6 +1502,9 @@ def _iter_shard_keys(
         """
         Iterate over the keys of the stored objects supporting this array.
 
+        Although only stored objects, e.g. shards should have keys, in case no
+        shards are present this automatically falls back to chunks.
+
         Parameters
         ----------
         origin : Sequence[int] | None, default=None
@@ -1506,7 +1515,8 @@ def _iter_shard_keys(
         Yields
         ------
         key: str
-            The storage key of each chunk in the selection.
+            The storage key of each shard in the selection or in case of no shard
+            present of each chunk although the latter case as technically incorrect.
         """
         # Iterate over the coordinates of chunks in chunk grid space.
         return _iter_shard_keys(
@@ -1545,6 +1555,8 @@ def _iter_shard_regions(
         """
         Iterate over the regions spanned by each shard.
 
+        This will automatically fall back to chunks if no shards are present.
+
         Parameters
         ----------
         origin : Sequence[int] | None, default=None
@@ -1555,7 +1567,8 @@ def _iter_shard_regions(
         Yields
         ------
         region: tuple[slice, ...]
-            A tuple of slice objects representing the region spanned by each shard in the selection.
+            A tuple of slice objects representing the region spanned by each shard in the selection or chunk in the
+            absence of shards.
         """
         return _iter_shard_regions(array=self, origin=origin, selection_shape=selection_shape)
 
@@ -2640,6 +2653,9 @@ def _iter_shard_keys(
         Iterate over the storage keys of each shard, relative to an optional origin, and optionally
         limited to a contiguous region in chunk grid coordinates.
 
+        If no shards are present this falls back to chunks, though in this case these are then actually
+        not storage keys.
+
         Parameters
         ----------
         origin : Sequence[int] | None, default=None
@@ -2650,7 +2666,8 @@ def _iter_shard_keys(
         Yields
         ------
         str
-            The storage key of each shard in the selection.
+            The storage key of each shard in the selection or chunk though chunks technically do not have
+            storage keys.
         """
         return self.async_array._iter_shard_keys(origin=origin, selection_shape=selection_shape)
 
@@ -2730,7 +2747,7 @@ def _iter_shard_regions(
         self, origin: Sequence[int] | None = None, selection_shape: Sequence[int] | None = None
     ) -> Iterator[tuple[slice, ...]]:
         """
-        Iterate over the regions spanned by each shard.
+        Iterate over the regions spanned by each shard or chunk if no shard is present.
 
         Parameters
         ----------
@@ -2742,7 +2759,8 @@ def _iter_shard_regions(
         Yields
         ------
         tuple[slice, ...]
-            A tuple of slice objects representing the region spanned by each chunk in the selection.
+            A tuple of slice objects representing the region spanned by each shard or if no shard is present,
+            chunk in the selection.
         """
         return self.async_array._iter_shard_regions(origin=origin, selection_shape=selection_shape)
 
@@ -4275,7 +4293,9 @@ async def _shards_initialized(
     array: AnyAsyncArray,
 ) -> tuple[str, ...]:
     """
-    Return the keys of the chunks that have been persisted to the storage backend.
+    Return the keys of the shards that have been persisted to the storage backend.
+
+    This will fall back to chunks in case no shards are present.
 
     Parameters
     ----------
@@ -4285,7 +4305,7 @@ async def _shards_initialized(
     Returns
     -------
     chunks_initialized : tuple[str, ...]
-        The keys of the chunks that have been initialized.
+        The keys of the shards or if these are not present, chunks that have been initialized.
 
     Related
     -------
@@ -5560,6 +5580,8 @@ def _iter_shard_coords(
     If the `selection_shape` keyword is used, iteration will be bounded over a contiguous region
     ranging from `[origin, origin selection_shape]`, where the upper bound is exclusive as
     per python indexing conventions.
+    If no shards are present this will iterate over the coordinates of chunks in chunk grid space
+    instead.
 
     Parameters
     ----------
@@ -5573,7 +5595,7 @@ def _iter_shard_coords(
     Yields
     ------
     chunk_coords: tuple[int, ...]
-        The coordinates of each shard in the selection.
+        The coordinates of each shard in the selection or chunks if no shards are present.
     """
     return _iter_grid(array._shard_grid_shape, origin=origin, selection_shape=selection_shape)
 
@@ -5588,6 +5610,8 @@ def _iter_shard_keys(
     Iterate over the storage keys of each shard, relative to an optional origin, and optionally
     limited to a contiguous region in shard grid coordinates.
 
+    This automatically falls back to chunks when no shards are present.
+
     Parameters
     ----------
     array : Array | AsyncArray
@@ -5600,7 +5624,7 @@ def _iter_shard_keys(
     Yields
     ------
     key: str
-        The storage key of each chunk in the selection.
+        The storage key of each shard in the selection or chunk when no shards are present.
     """
     # Iterate over the coordinates of chunks in chunk grid space.
     _iter = _iter_grid(array._shard_grid_shape, origin=origin, selection_shape=selection_shape)
@@ -5616,7 +5640,8 @@ def _iter_shard_regions(
     """
     Iterate over the regions spanned by each shard.
 
-    These are the smallest regions of the array that are safe to write concurrently.
+    These are the smallest regions of the array that are safe to write concurrently. When
+    no shards are present this will fall back to chunks.
 
     Parameters
     ----------
@@ -5630,12 +5655,13 @@ def _iter_shard_regions(
     Yields
     ------
     region: tuple[slice, ...]
-        A tuple of slice objects representing the region spanned by each shard in the selection.
+        A tuple of slice objects representing the region spanned by each shard in the selection or chunk
 
     Raises
     ------
     NotImplementedError
         If the array uses RectilinearChunkGrid (variable-sized chunks).
+        when no shards are present.
     """
     chunks = array.chunks
     if not isinstance(chunks, RegularChunks):

src/zarr/core/common.py

@@ -42,7 +42,7 @@
 ChunkCoords = tuple[int, ...]
 ZarrFormat = Literal[2, 3]
 NodeType = Literal["array", "group"]
-JSON = str | int | float | Mapping[str, "JSON"] | Sequence["JSON"] | None
+JSON = str | int | float | bool | Mapping[str, "JSON"] | Sequence["JSON"] | None
 MemoryOrder = Literal["C", "F"]
 AccessModeLiteral = Literal["r", "r+", "a", "w", "w-"]
 ANY_ACCESS_MODE: Final = "r", "r+", "a", "w", "w-"

tests/test_metadata/test_v2.py

@@ -309,12 +309,13 @@ def test_from_dict_extra_fields() -> None:
 
 
 def test_zstd_checksum() -> None:
+    compressor_config: dict[str, JSON] = {"id": "zstd", "level": 5, "checksum": False}
     arr = zarr.create_array(
         {},
         shape=(10,),
         chunks=(10,),
         dtype="int32",
-        compressors={"id": "zstd", "level": 5, "checksum": False},
+        compressors=compressor_config,
         zarr_format=2,
     )
     metadata = json.loads(