diff --git a/changes/3303.doc.md b/changes/3303.doc.md new file mode 100644 index 0000000000..ebae05f7e4 --- /dev/null +++ b/changes/3303.doc.md @@ -0,0 +1 @@ +Document different values of StoreLike with examples in the user guide. \ No newline at end of file diff --git a/docs/user-guide/storage.md b/docs/user-guide/storage.md index 86dac188a5..ea48f8f622 100644 --- a/docs/user-guide/storage.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 009f6a52ee..53b8eef7d4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -107,6 +107,7 @@ extra_css: - overrides/stylesheets/extra.css plugins: + - autorefs - search - markdown-exec - mkdocstrings: diff --git a/src/zarr/api/asynchronous.py b/src/zarr/api/asynchronous.py index 881341ace2..179f1ddb4a 100644 --- a/src/zarr/api/asynchronous.py +++ b/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 diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py index 728822a326..8713f55daf 100644 --- a/src/zarr/api/synchronous.py +++ b/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 diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index 6aefc38031..59ca8f5929 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -499,7 +499,9 @@ async def create( Parameters ---------- store : StoreLike - The store where the array will be created. + The store where the array will be created. See the + [storage documentation in the user guide][user-guide-store-like] + for a description of all valid StoreLike values. shape : ShapeLike The shape of the array. dtype : ZDTypeLike @@ -967,7 +969,9 @@ async def open( Parameters ---------- store : StoreLike - The store containing the Zarr array. + The store containing the Zarr array. See the + [storage documentation in the user guide][user-guide-store-like] + for a description of all valid StoreLike values. zarr_format : ZarrFormat | None, optional The Zarr format version (default is 3). @@ -2033,7 +2037,9 @@ def create( Parameters ---------- store : StoreLike - The array store that has already been initialized. + The array store that has already been initialized. See the + [storage documentation in the user guide][user-guide-store-like] + for a description of all valid StoreLike values. shape : tuple[int, ...] The shape of the array. dtype : ZDTypeLike @@ -2233,7 +2239,9 @@ def open( Parameters ---------- store : StoreLike - Store containing the Array. + Store containing the Array. See the + [storage documentation in the user guide][user-guide-store-like] + for a description of all valid StoreLike values. Returns ------- @@ -4251,7 +4259,9 @@ async 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 @@ -4735,7 +4745,9 @@ async 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. diff --git a/src/zarr/core/group.py b/src/zarr/core/group.py index e71c55c10f..71d2b52194 100644 --- a/src/zarr/core/group.py +++ b/src/zarr/core/group.py @@ -1823,7 +1823,9 @@ def from_store( Parameters ---------- store : StoreLike - StoreLike containing the Group. + StoreLike containing the Group. See the + [storage documentation in the user guide][user-guide-store-like] + for a description of all valid StoreLike values. attributes : dict, optional A dictionary of JSON-serializable values with user-defined attributes. zarr_format : {2, 3}, optional @@ -1863,7 +1865,9 @@ def open( Parameters ---------- store : StoreLike - Store containing the Group. + Store containing the Group. See the + [storage documentation in the user guide][user-guide-store-like] + for a description of all valid StoreLike values. zarr_format : {2, 3, None}, optional Zarr storage format version. diff --git a/src/zarr/storage/_common.py b/src/zarr/storage/_common.py index 4b1f5e4ae3..9ecfe4c201 100644 --- a/src/zarr/storage/_common.py +++ b/src/zarr/storage/_common.py @@ -283,7 +283,9 @@ async def make_store( Parameters ---------- store_like : StoreLike | None - The object to convert to a `Store` object. + The `StoreLike` object to convert to a `Store` object. See the + [storage documentation in the user guide][user-guide-store-like] + for a description of all valid StoreLike values. mode : StoreAccessMode | None, optional The mode to use when creating the `Store` object. If None, the default mode is 'r'. @@ -371,7 +373,9 @@ async def make_store_path( Parameters ---------- store_like : StoreLike or None, default=None - The object to convert to a `StorePath` object. + The `StoreLike` object to convert to a `StorePath` object. See the + [storage documentation in the user guide][user-guide-store-like] + for a description of all valid StoreLike values. path : str | None, optional The path to use when creating the `StorePath` object. If None, the default path is the empty string.