feat: export the metadata classes and ArraySpec from public modules

[d-v-b]

🤖 AI text below 🤖

Summary

Added public import paths for the metadata classes that Array.metadata and Group.metadata return: zarr.metadata.ArrayV2Metadata, ArrayV3Metadata, ArrayMetadata, GroupMetadata, and ConsolidatedMetadata. Added zarr.abc.codec.ArraySpec, the chunk description passed to codec methods. The API reference lists the members of each class that are public; construct the metadata classes with from_dict.

Before this PR, telling a v2 array from a v3 array with isinstance, or writing a codec against the public zarr.abc.codec classes, required importing from zarr.core. An audit of types reachable from the documented API found 74 with no public path; these are the ones users hold or must implement against.

For reviewers

• The documented surface is deliberately narrow. Each class gets an explicit members: list on its reference page, which under the definition proposed in docs: define the public API in the contributing guide #4501 makes only those members public. Left out: chunk_grid and chunk_key_encoding (their classes are private; the glossary already calls chunk-grid classes private API), extra_fields (typed with a private TypedDict), the update_* helpers, encode_chunk_key, to_buffer_dict, get_chunk_spec, and ArraySpec.config (typed with the private ArrayConfig; ArraySpec.order covers the common need). Any of these can be added later without breaking anyone.
• Constructors are not public. The pages say so and point at from_dict. This keeps room to move these classes onto zarr-metadata models later. The open question is ArraySpec: codec authors may want to build one in their own tests, which argues for making its constructor public.
• ArrayMetadata (the ArrayV2Metadata | ArrayV3Metadata union) is exported because it is the annotated type of Array.metadata.
• zarr.abc.codec now imports ArraySpec at runtime instead of under TYPE_CHECKING; there is no import cycle.
• Not included: the input aliases (ShapeLike, ChunksLike, ...), ArrayConfig, Attributes, and the indexer classes. Those are separate decisions.

Checks run locally: just docs-check (strict build; the rendered pages show exactly the listed members), tests/test_public_exports.py, plus tests/test_codecs, tests/test_metadata, tests/test_cli (1415 passed), ruff, and mypy.

Author attestation

• I am a human, these are my changes, and I have reviewed and understood every change and can explain why each is correct.

TODO

• Add unit tests and/or doctests in docstrings
• Add docstrings and API docs for any new/modified user-facing classes and functions
• New/modified features documented in docs/user-guide/*.md
• Changes documented as a new file in changes/
• GitHub Actions have all passed
• Test coverage is 100% (Codecov passes)

Stack notes

• Independent of docs: define the public API in the contributing guide #4501 and can merge in either order. The "documented members are the public API" reading comes from docs: define the public API in the contributing guide #4501's definition; until that merges, the page prose states it directly.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.70%. Comparing base (b996f03) to head (4a29001).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4502   +/-   ##
=======================================
  Coverage   94.69%   94.70%           
=======================================
  Files          94       95    +1     
  Lines       13619    13625    +6     
=======================================
+ Hits        12897    12903    +6     
  Misses        722      722           

Files with missing lines	Coverage Δ
src/zarr/abc/codec.py	98.80% <100.00%> (+0.01%)	⬆️
src/zarr/metadata/__init__.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.