ci: make the in-tree zarr-metadata resolvable by every environment

The zarr-metadata model layer that zarr now depends on is unreleased, and
the previous wiring only covered uv project flows, breaking everything else:

- The floor 'zarr-metadata>=0.4.0' is unresolvable from PyPI (only <0.4.0
  exists), failing every hatch env (test matrix, doctests, benchmarks,
  hypothesis, min_deps, upstream) and the readthedocs build. The floor now
  names the newest release (>=0.3) with a TODO to bump at release time, and
  each non-uv flow installs the in-tree package explicitly: hatch envs get a
  '{root:uri}/packages/zarr-metadata' direct reference (repeated per env,
  since hatch replaces extra-dependencies on inheritance), readthedocs gets
  an extra pip install step.

- uv workspace membership made 'uv sync' inside packages/zarr-metadata
  resolve the whole workspace, dragging zarr's requires-python (>=3.12) into
  the subpackage's own CI, which tests down to 3.11. The workspace is now a
  plain editable path source, restoring the subpackage's independence.

- min_deps pins typing_extensions==4.16.* (was 4.14.*): 4.16 is the
  effective minimum because zarr-metadata requires it for sentinel pickling.

Also fixes the Lint (mypy) findings in the new tests — a bare generic Array
annotation, stale type-ignores, and two sentinel comparisons mypy cannot
narrow (python/mypy#21647) — and renames the changelog entries to the PR
number (4129) required by the changelog check.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: d-v-b

.readthedocs.yaml

@@ -8,6 +8,11 @@ build:
     install:
       - pip install --upgrade pip
       - pip install .[remote] --group docs
+      # The in-tree zarr-metadata: zarr needs the unreleased model layer
+      # (ships in zarr-metadata 0.4.0); the project install above resolves
+      # the released 0.3.x from PyPI, which lacks it. Remove once the
+      # zarr-metadata floor in pyproject.toml is >=0.4.0.
+      - pip install ./packages/zarr-metadata
     pre_build:
       - |
         if [ "$READTHEDOCS_VERSION_TYPE" != "tag" ];

changes/+dtype_spelling.bugfix.md changes/4129.bugfix.mdchanges/+dtype_spelling.bugfix.md renamed to changes/4129.bugfix.md

@@ -37,7 +37,14 @@ dependencies = [
     'google-crc32c>=1.5',
     'typing_extensions>=4.14',
     'donfig>=0.8',
-    'zarr-metadata>=0.4.0',
+    # zarr needs the zarr-metadata model layer, which first ships in
+    # zarr-metadata 0.4.0 (not yet released). Until then the floor names the
+    # newest release on PyPI so plain-pip resolvers can proceed, and every
+    # dev/CI environment installs the in-tree package instead: uv flows via
+    # [tool.uv.sources], hatch envs via the `{root:uri}` direct reference in
+    # their extra-dependencies, readthedocs via an extra install step.
+    # TODO(release): bump to 'zarr-metadata>=0.4.0' once it is released.
+    'zarr-metadata>=0.3',
 ]
 
 dynamic = [
@@ -148,15 +155,15 @@ dev = [
     "mypy==2.1.0",
 ]
 
-# The repo is a uv workspace so that `zarr` can depend on the in-tree
-# `packages/zarr-metadata` during development and CI. Released wheels depend on
-# the published zarr-metadata distribution; the workspace source below only
-# affects resolution from a checkout (uv.lock, `uv run`, hatch envs using uv).
-[tool.uv.workspace]
-members = ["packages/zarr-metadata"]
-
+# uv flows from a checkout (uv.lock, `uv sync`, `uv run`) resolve
+# zarr-metadata to the in-tree package. This is a path source, deliberately
+# NOT a uv workspace: workspace membership would make `uv sync` inside
+# packages/zarr-metadata resolve the whole workspace, dragging zarr's
+# requires-python (>=3.12) and dependency set into the subpackage's own CI
+# (which tests down to Python 3.11). Released wheels depend on the published
+# zarr-metadata distribution; this source only affects checkouts.
 [tool.uv.sources]
-zarr-metadata = { workspace = true }
+zarr-metadata = { path = "packages/zarr-metadata", editable = true }
 
 [tool.coverage.report]
 exclude_also = [
@@ -180,11 +187,22 @@ version.raw-options = { git_describe_command = "git describe --dirty --tags --lo
 [tool.hatch.build]
 hooks.vcs.version-file = "src/zarr/_version.py"
 
+# Hatch envs resolve project dependencies from PyPI and do not read
+# [tool.uv.sources], so each env that defines its own environment installs the
+# in-tree zarr-metadata via a direct reference. Hatch replaces (does not
+# merge) extra-dependencies on inheritance, so every env repeats the line.
+# Remove these once zarr-metadata 0.4.0 is on PyPI and the floor is bumped.
 [tool.hatch.envs.dev]
 dependency-groups = ["dev"]
+extra-dependencies = [
+    "zarr-metadata @ {root:uri}/packages/zarr-metadata",
+]
 
 [tool.hatch.envs.test]
 dependency-groups = ["test"]
+extra-dependencies = [
+    "zarr-metadata @ {root:uri}/packages/zarr-metadata",
+]
 
 [tool.hatch.envs.test.env-vars]
 
@@ -225,6 +243,7 @@ list-env = "pip list"
 [tool.hatch.envs.gputest]
 template = "test"
 extra-dependencies = [
+    "zarr-metadata @ {root:uri}/packages/zarr-metadata",
     "universal_pathlib",
     # Needed so tests/test_docs.py is collectable under `pytest -m gpu`; otherwise its
     # module-level importorskip("pytest_examples") skips the whole module and the gpu
@@ -247,6 +266,7 @@ run = "pytest -m gpu --ignore tests/benchmarks"
 template = 'test'
 python = "3.14"
 extra-dependencies = [
+    'zarr-metadata @ {root:uri}/packages/zarr-metadata',
     'packaging @ git+https://github.com/pypa/packaging',
     'numpy',  # from scientific-python-nightly-wheels
     'numcodecs @ git+https://github.com/zarr-developers/numcodecs',
@@ -272,13 +292,16 @@ python = "3.12"
 features = ["remote"]
 dependency-groups = ["remote-tests"]
 extra-dependencies = [
+    'zarr-metadata @ {root:uri}/packages/zarr-metadata',
     'packaging==22.*',
     'numpy==2.0.*',
     'numcodecs==0.14.*',  # 0.14 needed for zarr3 codecs
     'fsspec==2023.10.0',
     's3fs==2023.10.0',
     'universal_pathlib==0.2.0',
-    'typing_extensions==4.14.*',
+    # 4.16 is the effective minimum: zarr-metadata requires >=4.16 for
+    # reference-picklable PEP 661 sentinels.
+    'typing_extensions==4.16.*',
     'donfig==0.8.*',
     'obstore==0.5.*',
 ]
@@ -289,6 +312,9 @@ installer = "uv"
 [tool.hatch.envs.docs]
 features = ['remote']
 dependency-groups = ['docs']
+extra-dependencies = [
+    "zarr-metadata @ {root:uri}/packages/zarr-metadata",
+]
 
 [tool.hatch.envs.docs.env-vars]
 DISABLE_MKDOCS_2_WARNING = "true"
@@ -305,6 +331,7 @@ description = "Test environment for validating executable code blocks in documen
 features = ['remote']
 dependency-groups = ['remote-tests']
 extra-dependencies = [
+    "zarr-metadata @ {root:uri}/packages/zarr-metadata",
     "pytest-examples",
 ]
 

changes/+future_metadata.feature.md changes/4129.feature.mdchanges/+future_metadata.feature.md renamed to changes/4129.feature.md

@@ -29,8 +29,9 @@
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-    from zarr import Array, Group
+    from zarr import Group
     from zarr.core.common import ZarrFormat
+    from zarr.types import AnyArray
 
 
 @pytest.mark.parametrize("zarr_format", [2, 3])
@@ -186,7 +187,7 @@ def test_attrs_interface_does_not_warn() -> None:
 
 
 @pytest.mark.parametrize("node_factory", NODE_CASES.values(), ids=NODE_CASES.keys())
-def test_node_picklable_with_populated_cache(node_factory: Callable[[], Array | Group]) -> None:
+def test_node_picklable_with_populated_cache(node_factory: Callable[[], AnyArray | Group]) -> None:
     """A node whose _future_metadata cache is populated pickles, and the
     restored node re-derives an equal model. The cache itself is derived
     state and is excluded from pickled state."""

pyproject.toml

@@ -14,6 +14,7 @@
     ZarrV2ArrayMetadata,
     ZarrV2GroupMetadata,
     ZarrV3ArrayMetadata,
+    ZarrV3ConsolidatedMetadata,
     ZarrV3GroupMetadata,
     ZarrV3NamedConfig,
 )
@@ -34,7 +35,7 @@
 
 
 @pytest.mark.filterwarnings("ignore::zarr.core.dtype.common.UnstableSpecificationWarning")
-@given(metadata=array_metadata())  # type: ignore[misc]
+@given(metadata=array_metadata())
 @settings(max_examples=100)
 def test_array_metadata_round_trip(metadata: ArrayV2Metadata | ArrayV3Metadata) -> None:
     """Runtime -> model -> runtime is the identity (runtime equality compares
@@ -48,7 +49,7 @@ def test_array_metadata_round_trip(metadata: ArrayV2Metadata | ArrayV3Metadata)
 
 
 @pytest.mark.filterwarnings("ignore::zarr.core.dtype.common.UnstableSpecificationWarning")
-@given(metadata=array_metadata())  # type: ignore[misc]
+@given(metadata=array_metadata())
 @settings(max_examples=100)
 def test_array_metadata_model_stable(metadata: ArrayV2Metadata | ArrayV3Metadata) -> None:
     """The model's own document form re-parses to an equal model: conversion
@@ -133,7 +134,10 @@ def test_group_metadata_v3_round_trip(attributes: dict[str, object]) -> None:
     metadata = GroupMetadata(attributes=attributes, zarr_format=3)
     model = group_metadata_to_model(metadata)
     assert isinstance(model, ZarrV3GroupMetadata)
-    assert model.consolidated_metadata is UNSET
+    # Absence is asserted on the document form rather than via `is UNSET`:
+    # mypy lacks PEP 661 sentinel narrowing (python/mypy#21647) and marks
+    # statements after a sentinel check unreachable.
+    assert "consolidated_metadata" not in model.to_json()
     assert group_metadata_from_model(model) == metadata
 
 
@@ -175,7 +179,9 @@ def test_group_metadata_v3_consolidated_round_trip() -> None:
     )
     model = group_metadata_to_model(metadata)
     assert isinstance(model, ZarrV3GroupMetadata)
-    assert model.consolidated_metadata is not UNSET
+    # isinstance rather than `is not UNSET`: mypy lacks PEP 661 sentinel
+    # narrowing (python/mypy#21647).
+    assert isinstance(model.consolidated_metadata, ZarrV3ConsolidatedMetadata)
     # The model holds consolidated entries flat, keyed by full path.
     assert set(model.consolidated_metadata.metadata) == {
         "child-group",