feat(typing)!: make the spec type parameters covariant - #191

🤖 AI text below 🤖

The spec type parameters (TAttr, TItem) are now covariant, in v2 and v3: the specs are frozen, so both parameters appear only in read positions on instances, and a narrowed spec is substitutable for a wider one. The Any* aliases (AnyArraySpec, AnyGroupSpec, AnyBaseGroupSpec) become ordinary wide types (ArraySpec[TBaseAttr] and friends) instead of gradual-typing escapes, so attributes and members read through them — including the results of resolve_path, from_flat and the is_*_spec guards — keep checked types instead of Any. The constructing classmethods (from_array) take attributes: TBaseAttr instead of TAttr, since a covariant parameter may not appear in argument positions: the argument is checked against the class's attribute type by validation rather than statically, which is the trade that keeps Self return types for subclasses.

Design notes

• This supersedes the bound/default split fix(typing): accept narrowed member specs in the TItem bound #190 introduced: with covariance, TBaseItem's bare, recursive spelling serves as both TItem's bound and its default again, and TAnyItem is deleted. The default's bare spelling remains load-bearing at runtime — it is the pydantic schema for a bare GroupSpec's members, validating nested members as specs all the way down.
• changes/190.bugfix.md is rewritten to describe the merged end state (both fragments render in the same release notes).
• On the from_array signature, the alternative — a method-scoped TypeVar (cls: type[ArraySpec[A]]) — would keep static checking of the attributes argument but lose Self returns, which downstream subclasses rely on (DataArray.from_array returning DataArray). The conformance file records the chosen trade-off.

Testing

• Full suite green across the zarr-python matrix (19,819); pyrefly, ty, pyright and ruff clean; pydantic's runtime is indifferent to variance declarations.
• tests/typing_conformance.py gains covariant-widening functions (narrowed array/group → Any* alias) and a checked-read assertion; ty and pyright each report 7 diagnostics if covariant=True is removed, 0 with it.
• Verified against eopf-geozarr (the pyright-checked downstream from fix(typing): accept narrowed member specs in the TItem bound #190): whole-repo pyright 0 errors and its data_api test suite passes with this branch installed.
• The roborev review of the covariance commit produced three findings (stale fix(typing): accept narrowed member specs in the TItem bound #190 fragment, undocumented from_array trade-off, leftover literal Any parameterizations in from_flat); all are addressed in the follow-up commit.

🤖 Generated with Claude Code