`zarr.{array,config,group}` are both modules and functions

[dstansby]

In v3 zarr.{array,config,group} are all defined as modules and functions, which could lead to some confusion, and is causing errors over in the API doc build PR: #2002

I think it makes sense to remove this duplication - perhaps by renaming the modules to _{array,config,group} if classes/functions in these sub-modules is designed to be imported and accessed through the zarr namespace?

[d-v-b]

I think the array and group functions exist for compatibility with v2. From a style perspective I think we should not have top-level functions with names like array or group; functions are (in this context) verbs, but these names are nouns, so the name conveys very little about what those functions do. Additionally, for each one there's a renaming that does convey what those functions do. As I would rather not rename modules just to accommodate legacy v2 APIs, we might have to sort this out after we have fully deprecated the zarr-python 2.x API.

config, on the other hand, is not a function and it's new in 3.x, so I'm think we have some flexibility for renaming here.

[jhamman]

An option I'd like to put forward is to move most of these modules to a new directory (e.g. _core). We should consider the top level namespace to be public API (including any modules, functions, or classes).

Here is a proposed module layout that would address this issue and go a long way to clearing up the definition of public and private API.

zarr.abc
  - codec
  - metadata
  - store
zarr.api
  - asynchronous
  - synchronous
zarr.testing
  - store
  - utils
zarr._core
  - array (only expose Array and AsyncArray classes)
  - array_spec
  - attributes
  - buffer
  - chunk_grids
  - chunk_key_encodings
  - codecs (or in zarr.codecs if we are confident the API is ready to go public)
  - common
  - config (only expose config object)
  - convenience (deprecated)
  - creation (deprecated)
  - group (only expose Group and AsyncGroup classes)
  - indexing
  - metadata 
  - stores (directory containing local, memory, and remote stores)
  - sync

[jhamman]

@zarr-developers/python-core-devs - anyone have a perspective to share here?

[martindurant]

Obviously, we break a bunch of stuff whenever things move around - but v3 is a breakage anyway. The function/module conflict and the verb/noun conflict are both indeed annoying. I probably wouldn't be too bothered to fix them - these are common enough patterns elsewhere, but I am happy if other people do want.

[dstansby]

PR for zarr._array at #2043. Given that the zarr.{array,group,config} namespaces re not documented in v2 (https://zarr.readthedocs.io/en/stable/api.html), I think renaming them is a good solution for v3.