fix(zarr-metadata): make JSONValue's array arm covariant - #4264
Merged
Conversation
`list["JSONValue"] | tuple["JSONValue", ...]` is invariant in the element type, so a value typed with any narrower element -- a `list[str]` field on a TypedDict, a `Sequence[float]` -- was not assignable to `JSONValue`, and a TypedDict carrying such fields was not assignable to `Mapping[str, JSONValue]`. pyright's diagnostic for the failure suggests the fix verbatim: "Consider switching from list to Sequence which is covariant." The array arm is now `Sequence["JSONValue"]`. The docstring records the deliberate type-level cost (`Sequence` admits `str`/`bytes`; runtime narrowing must exclude them regardless of the alias's spelling). Found while aliasing zarr-cm's JsonValue to this type: the two aliases are structurally identical except for this arm, and with it changed, pyright unifies them across the package boundary. Assisted-by: ClaudeCode:claude-opus-5
github-actions
Bot
added
the
needs release notes
Contributor
Author
|
SMWG (self-merge when green) |
d-v-b
marked this pull request as ready for review
August 14, 2026 09:50
d-v-b
added a commit
to d-v-b/zarr-python
that referenced
this pull request
Aug 14, 2026
Consume the pending news fragments — zarr-developers#4232's constant-naming-grammar removal note, zarr-developers#4264's note widening `JSONValue`'s array arm to the covariant `Sequence`, and zarr-developers#4248's sdist allowlist — into CHANGELOG.md via towncrier for the zarr_metadata-v0.5.0 release. Minor, not patch: the `JSONValue` widening changes a published type's meaning for every consumer that annotates against it, and zarr-developers#4232 removes the old version-last constant spellings outright. Assisted-by: ClaudeCode:claude-opus-5
d-v-b
added a commit
that referenced
this pull request
Aug 14, 2026
* chore(zarr-metadata): note the sdist allowlist, and let misc entries speak #4248 gave this package's sdist an explicit allowlist and merged without a news fragment, so a user-visible packaging change was about to miss the 0.5.0 notes. Add one. Filing it as `misc` exposed that towncrier's built-in `misc` type sets `showcontent = false`: the entry would render as a bare PR link, which tells a reader nothing. Restate all five types the `changes/README.md` menu offers — declaring any type replaces the built-in set — as the defaults verbatim except for `misc`, which now shows its content. A change worth a release note is worth a sentence, whatever its category. Assisted-by: ClaudeCode:claude-opus-5 * chore(zarr-metadata): build 0.5.0 changelog Consume the pending news fragments — #4232's constant-naming-grammar removal note, #4264's note widening `JSONValue`'s array arm to the covariant `Sequence`, and #4248's sdist allowlist — into CHANGELOG.md via towncrier for the zarr_metadata-v0.5.0 release. Minor, not patch: the `JSONValue` widening changes a published type's meaning for every consumer that annotates against it, and #4232 removes the old version-last constant spellings outright. Assisted-by: ClaudeCode:claude-opus-5
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
list[T] | tuple[T]is invariant butSequence[T]is covariant. In the context of ourJSONValuetype, we want covariance, to support intuitive propagation of the "isintance" operator when narrowingJSONValue. That means we need to change ourJSONValueunion. This is technically a breaking change and so the next release of zarr-metadata will indicate this. Why is it breaking? because strings inhabitSequence[str], but notlist[JSONValue] | tuple[JSONValue]. Routines handlingJSONValue-shaped inputs will need to guard for strings where previously they did not. Low blast area but a teeny blast nonetheless.cc @kylebarron i doubt this affects zarrista but I will do a check in any case.
Written by claude, with an original PR here: d-v-b#295
Author attestation
TODO
docs/user-guide/*.mdchanges/