[d-v-b]

🤖 AI text below 🤖

Added zarr.create_v3_array, zarr.create_v3_group, zarr.create_v2_array and zarr.create_v2_group: creation functions that are native to URL pipelines and to one Zarr format each. Their keyword arguments are that format's metadata fields (for V3 shape, data_type, chunk_grid, codecs, chunk_key_encoding, fill_value, attributes, dimension_names, storage_transformers; for V2 shape, dtype, chunks, fill_value, order, dimension_separator, compressor, filters, attributes), with no translation layer between formats. Fields left at the new zarr.AUTO sentinel are computed from the shape, the data type and the configuration, while None keeps the meaning the metadata gives it (for example no compressor). A string location is always a URL pipeline such as "file:/data/example.zarr|zarr3:group/array", so its root must carry a scheme and a literal | in a local path is spelled %7C; a URLPipeline, a Store or a StorePath is accepted as well. Creation fails if a node already exists at the location unless overwrite=True.

This is the creation-side counterpart of the read-only zarr.open_url introduced in #7, and it stacks on that PR: until #7 merges, this diff includes its commits as well, and only the three commits listed in the notes below are new here. The same change is open against the feature/url-pipeline-object branch alone as d-v-b#394. The agent prepared it at d-v-b's direction, with the design settled in discussion beforehand.

Design

• One function per format, metadata fields as keyword arguments. create_array abstracts over Zarr formats, and the price is parameters like compressors, serializer, filters and shards that mean different things per format or exist in only one. These functions build ArrayV3Metadata / ArrayV2Metadata (or GroupMetadata) directly from their arguments and write it; there is nothing to translate.
• A single AUTO sentinel for every derived default. Every optional metadata argument whose default is computed (chunk grid from shape and dtype, codecs and compressor from the config, fill value from the dtype, V2 order from array.order) defaults to zarr.AUTO, a typing_extensions.Sentinel used in type position. None is never overloaded: on V2 it still means a null fill value, no compressor, or no filters. No "auto" strings appear in the new signatures. fill_value="auto" being a valid string fill value is the concrete reason an object sentinel is used.
• A string is always a pipeline. The location is str | URLPipeline | Store | StorePath. Strings are read as URL pipelines whose root must carry a scheme, so | is unambiguous and %7C is the escape. To make that escape work, file: and memory: pipeline roots now percent-decode their bodies, as any URL does; adapter segments still receive their bodies verbatim. A format segment that contradicts the function (zarr2: for create_v3_array) raises. Store and StorePath remain accepted because a URL cannot name an arbitrary Python store object.
• Creation never opens. overwrite=False (the default) raises ContainsArrayError / ContainsGroupError on an existing node; overwrite=True deletes it first. There is no mode string.

Also in this PR

• mypy is bumped from 2.3.1 to 2.4.0, the first release that accepts a PEP 661 sentinel in type position (pyright has supported it since 1.1.414).
• The _Unset enum in PipelineContext.resolve_preceding becomes a Sentinel for the same reason, and the creation functions drop a scheme check that URLPipeline.from_url now performs itself.

Not in this PR

• Migrating create_array and friends to AUTO, and aliasing DEFAULT_FILL_VALUE to it. Both are additive follow-ups once this shape has settled.
• A single create_at_url was considered and rejected: creation always knows whether it is making an array or a group, and one function could only learn that from its arguments, which is the hidden dispatch open_url was reshaped to avoid.

Stack and review notes

• Base: this repository's feature/url-pipeline-core. The branch is d-v-b:feature/create-v3, which stacks on d-v-b:feature/url-pipeline-object (refactor(url-pipeline): resolve pipelines from a URLPipeline object, never from plain strings #7); once refactor(url-pipeline): resolve pipelines from a URLPipeline object, never from plain strings #7 merges, the diff here shrinks to the creation work alone.
• Commits, in order: cb172df (V3 pair, AUTO, percent-decoding, mypy bump), d7c7b61 (V2 pair), 3294266 (Sentinel swap, redundant check removed).
• The full serial test suite was green at the tip (12936 passed); the docs examples for the storage and extending guides and every pre-commit hook were green at each commit.

🤖 Generated with Claude Code