top-level functions for reading, creating data

[d-v-b]

adds async and sync read_array, read_group, and read functions. read_array will read an array from storage. read_group does the same, but for groups, and read will try to read arrays or groups at the storage path. These functions wrap their respective creation functions, passing mode=r in each case.

I still need to add tests.

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)

[d-v-b]

in writing this PR I noticed that we don't have a create_array function, but we do have create_group. I don't like the asymmetry. We should fix that (by adding a create_array func).

[d-v-b]

in writing this PR I noticed that we don't have a create_array function, but we do have create_group. I don't like the asymmetry. We should fix that (by adding a create_array func).

I'm wrong, we don't have create_group! But we should! I think we should actually deprecate file-mode semantics across the board in favor of create_x, read_x functions.

[d-v-b]

This is ready for review. To summarize:

I created 5 new top-level exports:

• read_array
• read_group
• read
• create_array
• create_group

The goal for these functions is to directly support common access patterns without forcing users to worry about the semantics of the mode keyword, and to guard against accessing zarr data with an unintended access mode (e.g., getting mutable access to an array you only want to read).

[d-v-b]

Some feedback from the community meeting last week:

• One point of contention in this PR was the polymorphic read function, which returns either an array or group, depending on what's in the hierarchy. Personally I think this is invaluable for navigating unknown Zarr hierarchies, but others thought it was unnecessary or confusing. Does anyone else have thoughts?
• Should this PR contain deprecation warnings for functions that are being made less essential by this PR (e.g., open and create)?

[jhamman]

This looks great. Just one comment of substance. Let's get this in and start using it.

[jhamman]

Thanks @d-v-b and @normanrz - what a lift 🏋️‍♂️