(zarr-metadata) builder classes

[d-v-b]

we should define builder classes for the two metadata representations (the raw dict and the dataclass form) to support incrementally creating metadata. something like

incomplete_builder = ZarrV3ArrayMetadataBuilder.data_type("float64") # returns an incomplete metadata specification
complete_builder = ZarrV3ArrayMetadataBuilder.data_type().chunk_grid().attributes()....build() # returns ZarrV3ArrayMetadata

we can model the serialized state of an incomplete builder with the controversial "array metadata typeddict with optional fields" type.

I've never written this kind of object before so I will solicit feedback from folks with more experience e.g. @kylebarron who has builders in zarrista

[kylebarron]

I think builders can be a good idea when you have incomplete state that you want to build incrementally. Because then at the end you can validate the entire state inside of build.

It's cleanest if you have two classes, one that provides methods to modify the object. Then once you call build you get the other type, which doesn't expose any mutable methods.

I think the type hints for the ArrayBuilder class in zarrista should be a helpful guide, even if the code is in Rust