chore: run mypy from developer environment (zarr-developers#3972)

* chore: ignore docs/superpowers/ scratch directory

* chore: pin python 3.12 on hatch dev env

* chore: run mypy from hatch dev env, drop mirrors-mypy hook

Replace the pre-commit/mirrors-mypy hook (which maintained its own
duplicate dep list) with a `repo: local` hook that runs
`hatch run dev:mypy`. The dev hatch env's `dev` group (resolved via
uv.lock) becomes the single source of truth for mypy's dependency set.

This also unpins numpy from the type-check environment (it was
hard-pinned to `numpy==2.1` in the old hook); type fixes that follow
keep mypy clean against current numpy stubs:

  - relax NDArrayLike.reshape/all signatures so np.ndarray
    structurally satisfies the protocol
  - widen AsyncGroup.require_array's `dtype` to include None
  - add narrowly-scoped `# type: ignore` comments with explanatory
    notes where numpy 2.x stubs are too strict against runtime-valid
    calls (datetime64 unit f-strings, 'generic' unit sentinel,
    newbyteorder subclass identity, ZDTypeLike None handling)
  - drop stale `# type: ignore` comments that are no longer needed

* ci: install hatch in lint workflow so mypy hook can run

* docs: changelog for mypy-in-dev-env change

* refactor: resolve None dtype at create() boundary

`create()` accepts `dtype=None` (legacy v2 behavior: an unspecified
dtype defaults to float64). Previously this `None` was forwarded
untyped into `_create`, which doesn't accept `None` — it only worked
because `parse_dtype(None)` -> `np.dtype(None)` happens to resolve to
float64. That required a `cast()` to silence mypy.

Resolve `None` to `"float64"` explicitly in `create()` before
forwarding, so the value passed to `_create` is a real dtype and the
cast is no longer needed. No behavior change.

* refactor: give NDArrayLike.reshape/all precise signatures

The initial fix for numpy-stub conformance widened the NDArrayLike
protocol's `reshape` and `all` to `(*args: Any, **kwargs: Any) -> Any`,
which erased type information for every consumer of the protocol.

Replace with precise signatures that np.ndarray still satisfies
structurally:

  - `reshape(shape: tuple[int, ...], /, *, order=..., copy=...)
    -> NDArrayLike` — the `Literal[-1]` form was the only thing
    blocking a precise signature (it straddles numpy's arity-split
    overloads); it is unused on protocol-typed values, so drop it.
    `NDBuffer.reshape` keeps its public `-1` support by normalizing
    `-1` to `(-1,)` before forwarding.
  - `all(self) -> np.bool_` — the sole caller wraps the result in
    `bool(...)`, and no-arg is all we use.

* chore: remove gitignore for claude docs

* chore: restore uv.lock

uv.lock was removed in zarr-developers#3962 as unused. The mypy-via-hatch change in
this branch makes it load-bearing again: it is the single source of
truth that keeps the `dev` hatch environment (and therefore mypy's
results) consistent across developer machines and CI. Restore it,
regenerated against the current pyproject.toml.

* docs: rename changelog entry to PR zarr-developers#3972

* ci: skip mypy hook on pre-commit.ci

The mypy hook is now `language: system` and shells out to
`hatch run dev:mypy`, which needs the project's hatch dev environment.
pre-commit.ci's hosted runners don't have it, so the hook can only
fail there. Add it to `ci.skip`; mypy is still covered by the Lint
GitHub Actions workflow (which installs hatch) and by local prek runs.

* refactor: apply review nitpicks from PR zarr-developers#3972

- Inline the float64 dtype default into the `_create` call instead of
  reassigning the `dtype` variable.
- Move the numpy 2.x stub explanation onto its own line above the code
  so `# type: ignore` comment lines stay short.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* ci: run mypy via `uv run` so the lockfile is actually honored

`hatch run dev:mypy` does not consume `uv.lock` — hatch has no lockfile
support and re-resolves the `dev` dependency group from scratch each time
it builds the environment. This defeated the PR's goal of a reproducible
type-checking environment: contributors with stale or differently-resolved
hatch `dev` envs saw different mypy results (e.g. errors from an older
`tomlkit` whose `TOMLDocument.__getitem__` was typed `Item | Container`
rather than `Any`).

Switch the mypy pre-commit hook and the Lint workflow to `uv run --frozen
mypy`. `uv` does sync from `uv.lock`, so the committed lockfile becomes the
real single source of truth for mypy's dependency set, identical for every
contributor and for CI.

- .pre-commit-config.yaml: hook entry `hatch run dev:mypy` -> `uv run --frozen mypy`
- .github/workflows/lint.yml: install `uv` instead of `hatch`
- pyproject.toml / changes: update wording to match

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Apply suggestion from @maxrjones

Co-authored-by: Max Jones <14077947+maxrjones@users.noreply.github.com>

* fix: test dtype is None exactly, not via falsy collapse

`dtype or "float64"` substitutes the default for any falsy input —
empty string, 0, empty Mapping — not just None. Those wouldn't pass
ZDTypeLike validation anyway, but the failure mode was "silent
substitution to float64" instead of "raise on invalid input".
Use an exact `is None` check expressed as a conditional expression.

* chore: add .python-version pinning default to 3.12

uv reads `.python-version` to decide which interpreter to use for
`uv venv` / `uv sync` / `uv run`. With the mypy hook now running as
`uv run --frozen mypy`, pinning the interpreter here keeps the dev
env consistent across developer machines — matching the existing
`[tool.mypy].python_version = "3.12"` and `requires-python = ">=3.12"`
declarations.

`.python-version` is not consumed by hatch (its envs declare their
own Python via `[tool.hatch.envs.*].python`), so the test matrix
(py3.12/3.13/3.14) is unaffected.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Max Jones <14077947+maxrjones@users.noreply.github.com>

Author: 3 people

.github/workflows/lint.yml

@@ -22,4 +22,12 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
       - uses: j178/prek-action@6ad80277337ad479fe43bd70701c3f7f8aa74db3 # v2.0.3

.pre-commit-config.yaml

@@ -2,7 +2,11 @@ ci:
   autoupdate_commit_msg: "chore: update pre-commit hooks"
   autoupdate_schedule: "monthly"
   autofix_prs: false
-  skip: []  # pre-commit.ci only checks for updates, prek runs hooks locally
+  # mypy runs as a `language: system` hook via `uv run mypy`, which needs `uv`
+  # and the repo checkout to resolve the dev environment from `uv.lock` —
+  # unavailable on pre-commit.ci's runners. It is covered instead by the Lint
+  # GitHub Actions workflow and by local prek runs.
+  skip: [mypy]
 
 default_stages: [pre-commit, pre-push]
 
@@ -27,25 +31,15 @@ repos:
       - id: check-yaml
         exclude: mkdocs.yml
       - id: trailing-whitespace
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.20.2
+  - repo: local
     hooks:
       - id: mypy
-        files: ^(src|tests)/
-        additional_dependencies:
-          # Package dependencies
-          - packaging
-          - donfig
-          - numcodecs
-          - google-crc32c>=1.5
-          - numpy==2.1 # https://github.com/zarr-developers/zarr-python/issues/3780 + https://github.com/zarr-developers/zarr-python/issues/3688
-          - typing_extensions
-          - universal-pathlib
-          - obstore>=0.5.1
-          # Tests
-          - pytest
-          - hypothesis
-          - s3fs
+        name: mypy
+        language: system
+        entry: uv run --frozen mypy
+        pass_filenames: false
+        always_run: true
+        types_or: [python, pyi]
   - repo: https://github.com/scientific-python/cookie
     rev: 2026.04.04
     hooks:

.python-version

@@ -0,0 +1 @@
+3.12

changes/3972.misc.md

@@ -0,0 +1 @@
+Run `mypy` via `uv run mypy` instead of `pre-commit`'s isolated venv. The `dev` dependency group in `pyproject.toml`, locked by `uv.lock`, is now the single source of truth for `mypy`'s dependency set, eliminating the duplicate dependency list previously maintained in `.pre-commit-config.yaml` and giving every contributor and CI an identical, reproducible type-checking environment.

pyproject.toml

@@ -30,7 +30,6 @@ maintainers = [
     { name = "Deepak Cherian" }
 ]
 requires-python = ">=3.12"
-# If you add a new dependency here, please also add it to .pre-commit-config.yaml
 dependencies = [
     'packaging>=22.0',
     'numpy>=2',
@@ -444,6 +443,7 @@ markers = [
 [tool.repo-review]
 ignore = [
 	"PC111",  # fix Python code in documentation - enable later
+    "PC140",  # we run mypy via `uv run mypy`, not via mirrors-mypy
     "PC170",  # use PyGrep hooks - no *.rst files to check
 	"PC180",  # for JavaScript - not interested
 	"PC902",  # pre-commit.ci custom autofix message - not using autofix

src/zarr/_compat.py

@@ -102,7 +102,7 @@ def _reshape_view(arr: "NDArray[Any]", shape: tuple[int, ...]) -> "NDArray[Any]"
         If a view cannot be created (the array is not contiguous) on NumPy >= 2.1.
     """
     if Version(np.__version__) >= Version("2.1"):
-        return arr.reshape(shape, copy=False)  # type: ignore[call-overload, no-any-return]
+        return arr.reshape(shape, copy=False)
     else:
         arr.shape = shape
         return arr

src/zarr/api/asynchronous.py

@@ -1049,7 +1049,8 @@ async def create(
         store_path,
         shape=shape,
         chunks=chunks,
-        dtype=dtype,
+        # Legacy v2 behavior: an unspecified dtype defaults to float64.
+        dtype="float64" if dtype is None else dtype,
         compressor=compressor,
         fill_value=fill_value,
         overwrite=overwrite,

src/zarr/codecs/cast_value.py

@@ -300,11 +300,11 @@ def _validate_scalar_map(
 
     def _do_cast(
         self,
-        arr: np.ndarray,  # type: ignore[type-arg]
+        arr: np.ndarray,
         *,
-        target_dtype: np.dtype,  # type: ignore[type-arg]
+        target_dtype: np.dtype,
         scalar_map: Mapping[str | float | int, str | float | int] | None,
-    ) -> np.ndarray:  # type: ignore[type-arg]
+    ) -> np.ndarray:
         if not _HAS_RUST_BACKEND:
             raise ImportError(
                 "The cast_value codec requires the 'cast-value-rs' package. "

src/zarr/core/buffer/core.py

@@ -71,8 +71,13 @@ def __setitem__(self, key: slice, value: Any) -> None: ...
     def __array__(self) -> npt.NDArray[Any]: ...
 
     def reshape(
-        self, shape: tuple[int, ...] | Literal[-1], *, order: Literal["A", "C", "F"] = ...
-    ) -> Self: ...
+        self,
+        shape: tuple[int, ...],
+        /,
+        *,
+        order: Literal["A", "C", "F"] | None = ...,
+        copy: bool | None = ...,
+    ) -> NDArrayLike: ...
 
     def view(self, dtype: npt.DTypeLike) -> Self: ...
 
@@ -92,7 +97,7 @@ def transpose(self, axes: SupportsIndex | Sequence[SupportsIndex] | None) -> Sel
 
     def ravel(self, order: Literal["K", "A", "C", "F"] = ...) -> Self: ...
 
-    def all(self) -> bool: ...
+    def all(self) -> np.bool_: ...
 
     def __eq__(self, other: object) -> Self:  # type: ignore[override]
         """Element-wise equal
@@ -502,7 +507,10 @@ def byteorder(self) -> Endian:
             return Endian(sys.byteorder)
 
     def reshape(self, newshape: tuple[int, ...] | Literal[-1]) -> Self:
-        return self.__class__(self._data.reshape(newshape))
+        # numpy accepts a bare -1, but the NDArrayLike protocol only types the
+        # tuple form; normalize so the forwarded value matches the protocol.
+        shape = (newshape,) if newshape == -1 else newshape
+        return self.__class__(self._data.reshape(shape))
 
     def squeeze(self, axis: tuple[int, ...]) -> Self:
         newshape = tuple(a for i, a in enumerate(self.shape) if i not in axis)

src/zarr/core/dtype/__init__.py

@@ -276,7 +276,7 @@ def parse_dtype(
     # First attempt to interpret the input as JSON
     if isinstance(dtype_spec, Mapping | str | Sequence):
         try:
-            return get_data_type_from_json(dtype_spec, zarr_format=zarr_format)  # type: ignore[arg-type]
+            return get_data_type_from_json(dtype_spec, zarr_format=zarr_format)
         except ValueError:
             # no data type matched this JSON-like input
             pass