Document StoreLike values in user guide (#3480)

* document valid values for StoreLike in user guide

* fix doctests for storelike examples

* make links mkdocs style

* fix user guide links for mkdocs

* link all StoreLike refs to the user guide

* add changes note

* remove old storage rst file

---------

Co-authored-by: Davis Bennett <[email protected]>

Author: K-Meech

changes/3303.doc.md

@@ -0,0 +1 @@
+Document different values of StoreLike with examples in the user guide.

docs/user-guide/storage.md

@@ -12,7 +12,8 @@ Zarr-Python 3, stores must implement the abstract store API from
 ## Implicit Store Creation
 
 In most cases, it is not required to create a `Store` object explicitly. Passing a string
-to Zarr's top level API will result in the store being created automatically:
+(or other [StoreLike value](#storelike)) to Zarr's top level API will result in the store
+being created automatically:
 
 ```python exec="true" session="storage" source="above" result="ansi"
 import zarr
@@ -39,6 +40,53 @@ group = zarr.create_group(store=data)
 print(group)
 ```
 
+[](){#user-guide-store-like}
+### StoreLike
+
+`StoreLike` values can be:
+
+- a `Path` or string indicating a location on the local file system.
+  This will create a [local store](#local-store):
+   ```python exec="true" session="storage" source="above" result="ansi"
+   group = zarr.open_group(store='data/foo/bar')
+   print(group)
+   ```
+   ```python exec="true" session="storage" source="above" result="ansi"
+   from pathlib import Path
+   group = zarr.open_group(store=Path('data/foo/bar'))
+   print(group)
+   ```
+
+- an FSSpec URI string, indicating a [remote store](#remote-store) location:
+   ```python exec="true" session="storage" source="above" result="ansi"
+   group = zarr.open_group(
+      store='s3://noaa-nwm-retro-v2-zarr-pds',
+      mode='r',
+      storage_options={'anon': True}
+   )
+   print(group)
+   ```
+
+- an empty dictionary or None, which will create a new [memory store](#memory-store):
+   ```python exec="true" session="storage" source="above" result="ansi"
+   group = zarr.create_group(store={})
+   print(group)
+   ```
+   ```python exec="true" session="storage" source="above" result="ansi"
+   group = zarr.create_group(store=None)
+   print(group)
+   ```
+
+- a dictionary of string to [`Buffer`][zarr.abc.buffer.Buffer] mappings. This will
+  create a [memory store](#memory-store), using this dictionary as the
+  [`store_dict` argument][zarr.storage.MemoryStore].
+
+- an FSSpec [FSMap object](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.FSMap),
+  which will create an [FsspecStore](#remote-store).
+
+- a [`Store`][zarr.abc.store.Store] or [`StorePath`][zarr.storage.StorePath] -
+  see explicit store creation below.
+
 ## Explicit Store Creation
 
 In some cases, it may be helpful to create a store instance directly. Zarr-Python offers four

mkdocs.yml

@@ -107,6 +107,7 @@ extra_css:
   - overrides/stylesheets/extra.css
 
 plugins:
+  - autorefs
   - search
   - markdown-exec
   - mkdocstrings:

src/zarr/api/asynchronous.py

@@ -199,7 +199,9 @@ async def consolidate_metadata(
     Parameters
     ----------
     store : StoreLike
-        The store-like object whose metadata you wish to consolidate.
+        The store-like object whose metadata you wish to consolidate. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     path : str, optional
         A path to a group in the store to consolidate at. Only children
         below that group will be consolidated.
@@ -293,7 +295,9 @@ async def load(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     path : str or None, optional
         The path within the store from which to load.
 
@@ -337,7 +341,9 @@ async def open(
     Parameters
     ----------
     store : StoreLike or None, default=None
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     mode : {'r', 'r+', 'a', 'w', 'w-'}, optional
         Persistence mode: 'r' means read only (must exist); 'r+' means
         read/write (must exist); 'a' means read/write (create if doesn't
@@ -421,7 +427,9 @@ async def save(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     *args : ndarray
         NumPy arrays with data to save.
     zarr_format : {2, 3, None}, optional
@@ -457,7 +465,9 @@ async def save_array(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     arr : ndarray
         NumPy array with data to save.
     zarr_format : {2, 3, None}, optional
@@ -513,7 +523,9 @@ async def save_group(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     *args : ndarray
         NumPy arrays with data to save.
     zarr_format : {2, 3, None}, optional
@@ -662,7 +674,9 @@ async def group(
     Parameters
     ----------
     store : StoreLike or None, default=None
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     overwrite : bool, optional
         If True, delete any pre-existing data in `store` at `path` before
         creating the group.
@@ -724,7 +738,9 @@ async def create_group(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     path : str, optional
         Group path within store.
     overwrite : bool, optional
@@ -780,17 +796,9 @@ async def open_group(
     Parameters
     ----------
     store : StoreLike or None, default=None
-        Store or path to directory in file system or name of zip file.
-
-        Strings are interpreted as paths on the local file system
-        and used as the ``root`` argument to [zarr.storage.LocalStore][].
-
-        Dictionaries are used as the ``store_dict`` argument in
-        [zarr.storage.MemoryStore][].
-
-        By default (``store=None``) a new [zarr.storage.MemoryStore][]
-        is created.
-
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     mode : {'r', 'r+', 'a', 'w', 'w-'}, optional
         Persistence mode: 'r' means read only (must exist); 'r+' means
         read/write (must exist); 'a' means read/write (create if doesn't
@@ -805,7 +813,9 @@ async def open_group(
     path : str, optional
         Group path within store.
     chunk_store : StoreLike or None, default=None
-        Store or path to directory in file system or name of zip file.
+        Separate storage for chunks. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     storage_options : dict
         If using an fsspec URL to create the store, these will be passed to
         the backend implementation. Ignored otherwise.
@@ -939,7 +949,9 @@ async def create(
         Memory layout to be used within each chunk.
         If not specified, the ``array.order`` parameter in the global config will be used.
     store : StoreLike or None, default=None
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     synchronizer : object, optional
         Array synchronizer.
     overwrite : bool, optional
@@ -1250,7 +1262,9 @@ async def open_array(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     zarr_version : {2, 3, None}, optional
         The zarr format to use when saving. Deprecated in favor of zarr_format.
     zarr_format : {2, 3, None}, optional

src/zarr/api/synchronous.py

@@ -88,7 +88,9 @@ def consolidate_metadata(
     Parameters
     ----------
     store : StoreLike
-        The store-like object whose metadata you wish to consolidate.
+        The store-like object whose metadata you wish to consolidate. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     path : str, optional
         A path to a group in the store to consolidate at. Only children
         below that group will be consolidated.
@@ -143,7 +145,9 @@ def load(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     path : str or None, optional
         The path within the store from which to load.
 
@@ -183,7 +187,9 @@ def open(
     Parameters
     ----------
     store : StoreLike or None, default=None
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     mode : {'r', 'r+', 'a', 'w', 'w-'}, optional
         Persistence mode: 'r' means read only (must exist); 'r+' means
         read/write (must exist); 'a' means read/write (create if doesn't
@@ -245,7 +251,9 @@ def save(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     *args : ndarray
         NumPy arrays with data to save.
     zarr_format : {2, 3, None}, optional
@@ -279,7 +287,9 @@ def save_array(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     arr : ndarray
         NumPy array with data to save.
     zarr_format : {2, 3, None}, optional
@@ -322,7 +332,9 @@ def save_group(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     *args : ndarray
         NumPy arrays with data to save.
     zarr_format : {2, 3, None}, optional
@@ -413,7 +425,9 @@ def group(
     Parameters
     ----------
     store : StoreLike or None, default=None
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     overwrite : bool, optional
         If True, delete any pre-existing data in `store` at `path` before
         creating the group.
@@ -480,17 +494,9 @@ def open_group(
     Parameters
     ----------
     store : StoreLike or None, default=None
-        Store or path to directory in file system or name of zip file.
-
-        Strings are interpreted as paths on the local file system
-        and used as the ``root`` argument to [zarr.storage.LocalStore][].
-
-        Dictionaries are used as the ``store_dict`` argument in
-        [zarr.storage.MemoryStore][].
-
-        By default (``store=None``) a new [zarr.storage.MemoryStore][]
-        is created.
-
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     mode : {'r', 'r+', 'a', 'w', 'w-'}, optional
         Persistence mode: 'r' means read only (must exist); 'r+' means
         read/write (must exist); 'a' means read/write (create if doesn't
@@ -505,7 +511,9 @@ def open_group(
     path : str, optional
         Group path within store.
     chunk_store : StoreLike or None, default=None
-        Store or path to directory in file system or name of zip file.
+        Separate storage for chunks. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     storage_options : dict
         If using an fsspec URL to create the store, these will be passed to
         the backend implementation. Ignored otherwise.
@@ -570,7 +578,9 @@ def create_group(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     path : str, optional
         Group path within store.
     overwrite : bool, optional
@@ -672,7 +682,9 @@ def create(
         Memory layout to be used within each chunk.
         If not specified, the ``array.order`` parameter in the global config will be used.
     store : StoreLike or None, default=None
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     synchronizer : object, optional
         Array synchronizer.
     overwrite : bool, optional
@@ -832,7 +844,9 @@ def create_array(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     name : str or None, optional
         The name of the array within the store. If ``name`` is ``None``, the array will be located
         at the root of the store.
@@ -996,7 +1010,9 @@ def from_array(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     data : Array | array-like
         The array to copy.
     write_data : bool, default True
@@ -1333,7 +1349,9 @@ def open_array(
     Parameters
     ----------
     store : StoreLike
-        Store or path to directory in file system or name of zip file.
+        StoreLike object to open. See the
+        [storage documentation in the user guide][user-guide-store-like]
+        for a description of all valid StoreLike values.
     zarr_version : {2, 3, None}, optional
         The zarr format to use when saving. Deprecated in favor of zarr_format.
     zarr_format : {2, 3, None}, optional