Fix create_dataset with data kwarg

[jni]

Closes #2631

• Add failing test for Group.create_dataset does not match 2.x API #2631
• Fix create_dataset with data argument

create_dataset is a legacy method for zarr v2 compatibility to help libraries
migrate to zarr v3. #2463 was a little overenthusiastic about the capabilities
of the new create_array method 😂 and missed one of the kwargs of
create_dataset. This PR adds special handling of the data kwarg before
passing the remaining arguments to create_array.

I also added special handling of the dtype kwarg because it is optional in 2.x
if data is passed. (For some reason, shape is not optional, and I thought
about fixing it but it seems pointless because the function is going to be
removed anyway, so we don't want to add new conveniences to it.)

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/tutorial.rst
• Changes documented in docs/release.rst
• GitHub Actions have all passed
• Test coverage is 100% (Codecov passes)

[will-moore]

Just to clarify... Is it intended that this change was only added to the deprecated group.create_dataset() and not to group.create_array()?

So we shouldn't expect this to be around too long and should migrate to doing this:

zarr_array = group.create_array(str(path), dtype=data.dtype, shape=data.shape, **options)
zarr_array[...] = data

[normanrz]

So we shouldn't expect this to be around too long and should migrate to doing this:

zarr_array = group.create_array(str(path), dtype=data.dtype, shape=data.shape, **options)
zarr_array[...] = data

Yes, I would recommend that.

[d-v-b]

we should definitely have a group-level method that lets people create + fill an array from an existing array.

[normanrz]

Maybe group.from_array(data, name, ..., write=True)? See #2622

[d-v-b]

that would be a perfect fit, but X.from_y() normally makes an instance of X. I wonder if there's a name re-arrangement that could make this not confusing

[d-v-b]

as_array I think is better than from_array in this context, thoughts? this would also affect #2622

[jni]

Is it intended that this change was only added to the deprecated group.create_dataset() and not to group.create_array()?

Not from my end. This was just what I needed to get the napari tests passing.

as_array I think is better than from_array in this context, thoughts?

I would find this confusing. create_array_from? create_from_array?

[jni]

So we shouldn't expect this to be around too long and should migrate to doing this:

The issue is that create_array doesn't exist in 2.x, so it's impossible to support both 2.x and 3.x with the create_array API. This is why I advocated for a much longer deprecation cycle for create_dataset. So far there hasn't been much discussion around the length of the deprecation though.

[normanrz]

What length of deprecation cycle would you recommend?

[jni]

minimum 6mo but preferably 24mo. (The latter being in line with SPEC0.)

[normanrz]

Thanks. I could get behind that but I think we need to have a discussion. I could also see different deprecation time scales for different APIs within the library.