From 97261ecf1653669675433a12d030d6e4e1e337c7 Mon Sep 17 00:00:00 2001 From: Kimberly Meechan <24316371+K-Meech@users.noreply.github.com> Date: Thu, 18 Sep 2025 17:47:51 +0100 Subject: [PATCH 1/7] document valid values for StoreLike in user guide --- docs/user-guide/storage.rst | 47 ++++++++++++++++++++++++++++++++++++- src/zarr/api/synchronous.py | 3 ++- 2 files changed, 48 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/storage.rst b/docs/user-guide/storage.rst index e5a333872e..03bbd0aa1d 100644 --- a/docs/user-guide/storage.rst +++ b/docs/user-guide/storage.rst @@ -21,7 +21,8 @@ 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 :ref:`StoreLike value `) to Zarr's top level API will result +in the store being created automatically.: >>> import zarr >>> @@ -42,6 +43,44 @@ to Zarr's top level API will result in the store being created automatically.: >>> zarr.create_group(store=data) +.. _user-guide-storelike: + +StoreLike +~~~~~~~~~~~ + +`StoreLike` values can be: + +- a `Path` or string indicating a :ref:`local store ` location e.g.: + + >>> zarr.open_group(store='data/foo/bar') + >>> zarr.open_group(store=Path('data/foo/bar')) + +- an FSSpec URI string, indicating a :ref:`remote store ` location e.g.: + + >>> zarr.open_group( + ... store='s3://noaa-nwm-retro-v2-zarr-pds', + ... mode='r', + ... storage_options={'anon': True} + ... ) + +- an empty dictionary or None, which will create a new :ref:`memory store `: + + >>> zarr.create_group(store={}) + >>> zarr.create_group(store=None) + +- a dictionary of string to :class:`Buffer ` mappings, which + will create a :ref:`memory store `: + + >>> example? + +- an FSSpec `FSMap object `_, + which will create an :ref:`FsspecStore `: + + >>> example? + +- a :class:`Store ` or :class:`StorePath ` - + see explicit store creation below. + Explicit Store Creation ----------------------- @@ -49,6 +88,8 @@ In some cases, it may be helpful to create a store instance directly. Zarr-Pytho built-in store: :class:`zarr.storage.LocalStore`, :class:`zarr.storage.FsspecStore`, :class:`zarr.storage.ZipStore`, :class:`zarr.storage.MemoryStore`, and :class:`zarr.storage.ObjectStore`. +.. _user-guide-local-store: + Local Store ~~~~~~~~~~~ @@ -69,6 +110,8 @@ Zip file. The `Zip Store specification`_ is currently in draft form.: >>> zarr.create_array(store=store, shape=(2,), dtype='float64') +.. _user-guide-remote-store: + Remote Store ~~~~~~~~~~~~ @@ -97,6 +140,8 @@ In case a specific filesystem is needed, one can explicitly create it. For examp ... ) >>> store = zarr.storage.FsspecStore(fs) +.. _user-guide-memory-store: + Memory Store ~~~~~~~~~~~~ diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py index d0134a4900..9792b91baa 100644 --- a/src/zarr/api/synchronous.py +++ b/src/zarr/api/synchronous.py @@ -183,7 +183,8 @@ def open( Parameters ---------- store : StoreLike or None, default=None - Store or path to directory in file system or name of zip file. + See the :ref:`storage documentation in the user guide ` + 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 From 73b6f135991c9c5e5dfe871e637d958a23a731f4 Mon Sep 17 00:00:00 2001 From: Kimberly Meechan <24316371+K-Meech@users.noreply.github.com> Date: Mon, 22 Sep 2025 10:43:01 +0100 Subject: [PATCH 2/7] fix doctests for storelike examples --- docs/user-guide/storage.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/user-guide/storage.rst b/docs/user-guide/storage.rst index 03bbd0aa1d..61de193d9c 100644 --- a/docs/user-guide/storage.rst +++ b/docs/user-guide/storage.rst @@ -53,7 +53,11 @@ StoreLike - a `Path` or string indicating a :ref:`local store ` location e.g.: >>> zarr.open_group(store='data/foo/bar') + + >>> + >>> from pathlib import Path >>> zarr.open_group(store=Path('data/foo/bar')) + - an FSSpec URI string, indicating a :ref:`remote store ` location e.g.: @@ -62,21 +66,21 @@ StoreLike ... mode='r', ... storage_options={'anon': True} ... ) + > - an empty dictionary or None, which will create a new :ref:`memory store `: >>> zarr.create_group(store={}) + + >>> >>> zarr.create_group(store=None) + - a dictionary of string to :class:`Buffer ` mappings, which - will create a :ref:`memory store `: - - >>> example? + will create a :ref:`memory store `. - an FSSpec `FSMap object `_, - which will create an :ref:`FsspecStore `: - - >>> example? + which will create an :ref:`FsspecStore `. - a :class:`Store ` or :class:`StorePath ` - see explicit store creation below. From 02360518a51b27a168b300ddada4484a1eb5b6d0 Mon Sep 17 00:00:00 2001 From: Kimberly Meechan <24316371+K-Meech@users.noreply.github.com> Date: Mon, 22 Sep 2025 14:39:41 +0100 Subject: [PATCH 3/7] make links mkdocs style --- docs/user-guide/storage.md | 23 ++++++++++------------- src/zarr/api/synchronous.py | 2 +- 2 files changed, 11 insertions(+), 14 deletions(-) diff --git a/docs/user-guide/storage.md b/docs/user-guide/storage.md index eebe073ef7..191a2c04c3 100644 --- a/docs/user-guide/storage.md +++ b/docs/user-guide/storage.md @@ -11,8 +11,9 @@ 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 (or other StoreLike value LINK) -to Zarr's top level API will result in the store being created automatically: +In most cases, it is not required to create a `Store` object explicitly. Passing a string +(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 @@ -43,21 +44,18 @@ print(group) `StoreLike` values can be: -- a `Path` or string indicating a :ref:`local store ` location e.g.: - +- a `Path` or string indicating a [local store](#local-store) location e.g.: ```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 :ref:`remote store ` location e.g.: - +- an FSSpec URI string, indicating a [remote store](#remote-store) location e.g.: ```python exec="true" session="storage" source="above" result="ansi" group = zarr.open_group( store='s3://noaa-nwm-retro-v2-zarr-pds', @@ -67,8 +65,7 @@ print(group) print(group) ``` -- an empty dictionary or None, which will create a new :ref:`memory store `: - +- 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) @@ -78,13 +75,13 @@ print(group) print(group) ``` -- a dictionary of string to :class:`Buffer ` mappings, which - will create a :ref:`memory store `. +- a dictionary of string to [`Buffer`][zarr.abc.buffer.Buffer] mappings, which + will create a [memory store](#memory-store). - an FSSpec [FSMap object](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.FSMap), - which will create an :ref:`FsspecStore `. + which will create an [FsspecStore](#remote-store). -- a :class:`Store ` or :class:`StorePath ` - +- a [`Store`][zarr.abc.store.Store] or [`StorePath`][zarr.storage.StorePath] - see explicit store creation below. ## Explicit Store Creation diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py index b478fc225e..50f333c753 100644 --- a/src/zarr/api/synchronous.py +++ b/src/zarr/api/synchronous.py @@ -183,7 +183,7 @@ def open( Parameters ---------- store : StoreLike or None, default=None - See the :ref:`storage documentation in the user guide ` + See the [`storage documentation in the user guide`][storelike] 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 From 6e0bccd92386b07f64057557ea2f6998fbf8c6ef Mon Sep 17 00:00:00 2001 From: Kimberly Meechan <24316371+K-Meech@users.noreply.github.com> Date: Mon, 22 Sep 2025 16:21:56 +0100 Subject: [PATCH 4/7] fix user guide links for mkdocs --- docs/user-guide/storage.md | 1 + mkdocs.yml | 1 + src/zarr/api/synchronous.py | 3 ++- 3 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/storage.md b/docs/user-guide/storage.md index 191a2c04c3..e2693c1ad7 100644 --- a/docs/user-guide/storage.md +++ b/docs/user-guide/storage.md @@ -40,6 +40,7 @@ group = zarr.create_group(store=data) print(group) ``` +[](){#user-guide-store-like} ### StoreLike `StoreLike` values can be: diff --git a/mkdocs.yml b/mkdocs.yml index c938ec36a8..cd32359f28 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -111,6 +111,7 @@ extra_css: - overrides/stylesheets/extra.css plugins: + - autorefs - search - markdown-exec - mkdocstrings: diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py index 50f333c753..ef9970c723 100644 --- a/src/zarr/api/synchronous.py +++ b/src/zarr/api/synchronous.py @@ -183,7 +183,8 @@ def open( Parameters ---------- store : StoreLike or None, default=None - See the [`storage documentation in the user guide`][storelike] + 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 From ab8c1d391519c4db3739ab31e48a07599c6ecaa9 Mon Sep 17 00:00:00 2001 From: Kimberly Meechan <24316371+K-Meech@users.noreply.github.com> Date: Mon, 22 Sep 2025 17:11:40 +0100 Subject: [PATCH 5/7] link all StoreLike refs to the user guide --- docs/user-guide/storage.md | 10 +++--- src/zarr/api/asynchronous.py | 58 ++++++++++++++++++++------------- src/zarr/api/synchronous.py | 62 +++++++++++++++++++++++------------- src/zarr/core/array.py | 24 ++++++++++---- src/zarr/core/group.py | 8 +++-- src/zarr/storage/_common.py | 8 +++-- 6 files changed, 111 insertions(+), 59 deletions(-) diff --git a/docs/user-guide/storage.md b/docs/user-guide/storage.md index e2693c1ad7..ea48f8f622 100644 --- a/docs/user-guide/storage.md +++ b/docs/user-guide/storage.md @@ -45,7 +45,8 @@ print(group) `StoreLike` values can be: -- a `Path` or string indicating a [local store](#local-store) location e.g.: +- 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) @@ -56,7 +57,7 @@ print(group) print(group) ``` -- an FSSpec URI string, indicating a [remote store](#remote-store) location e.g.: +- 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', @@ -76,8 +77,9 @@ print(group) print(group) ``` -- a dictionary of string to [`Buffer`][zarr.abc.buffer.Buffer] mappings, which - will create a [memory store](#memory-store). +- 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). 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 ef9970c723..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. @@ -247,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 @@ -281,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 @@ -324,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 @@ -415,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. @@ -482,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 @@ -507,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. @@ -572,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 @@ -674,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 @@ -834,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. @@ -998,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 @@ -1335,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. From f87a21c20c42db4f34af4f0c6645aba16138dba1 Mon Sep 17 00:00:00 2001 From: Kimberly Meechan <24316371+K-Meech@users.noreply.github.com> Date: Mon, 22 Sep 2025 17:45:47 +0100 Subject: [PATCH 6/7] add changes note --- changes/3303.doc.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 changes/3303.doc.md 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 From 593a84c54afa85f04e2b921babe51b831435281a Mon Sep 17 00:00:00 2001 From: Kimberly Meechan <24316371+K-Meech@users.noreply.github.com> Date: Mon, 22 Sep 2025 17:48:40 +0100 Subject: [PATCH 7/7] remove old storage rst file --- docs/user-guide/storage.rst | 207 ------------------------------------ 1 file changed, 207 deletions(-) delete mode 100644 docs/user-guide/storage.rst diff --git a/docs/user-guide/storage.rst b/docs/user-guide/storage.rst deleted file mode 100644 index 61de193d9c..0000000000 --- a/docs/user-guide/storage.rst +++ /dev/null @@ -1,207 +0,0 @@ -.. only:: doctest - - >>> import shutil - >>> shutil.rmtree('data', ignore_errors=True) - -.. _user-guide-storage: - -Storage guide -============= - -Zarr-Python supports multiple storage backends, including: local file systems, -Zip files, remote stores via fsspec_ (S3, HTTP, etc.), and in-memory stores. In -Zarr-Python 3, stores must implement the abstract store API from -:class:`zarr.abc.store.Store`. - -.. note:: - Unlike Zarr-Python 2 where the store interface was built around a generic ``MutableMapping`` - API, Zarr-Python 3 utilizes a custom store API that utilizes Python's AsyncIO library. - -Implicit Store Creation ------------------------ - -In most cases, it is not required to create a ``Store`` object explicitly. Passing a string -(or other :ref:`StoreLike value `) to Zarr's top level API will result -in the store being created automatically.: - - >>> import zarr - >>> - >>> # Implicitly create a writable LocalStore - >>> zarr.create_group(store='data/foo/bar') - - >>> - >>> # Implicitly create a read-only FsspecStore - >>> zarr.open_group( - ... store='s3://noaa-nwm-retro-v2-zarr-pds', - ... mode='r', - ... storage_options={'anon': True} - ... ) - > - >>> - >>> # Implicitly creates a MemoryStore - >>> data = {} - >>> zarr.create_group(store=data) - - -.. _user-guide-storelike: - -StoreLike -~~~~~~~~~~~ - -`StoreLike` values can be: - -- a `Path` or string indicating a :ref:`local store ` location e.g.: - - >>> zarr.open_group(store='data/foo/bar') - - >>> - >>> from pathlib import Path - >>> zarr.open_group(store=Path('data/foo/bar')) - - -- an FSSpec URI string, indicating a :ref:`remote store ` location e.g.: - - >>> zarr.open_group( - ... store='s3://noaa-nwm-retro-v2-zarr-pds', - ... mode='r', - ... storage_options={'anon': True} - ... ) - > - -- an empty dictionary or None, which will create a new :ref:`memory store `: - - >>> zarr.create_group(store={}) - - >>> - >>> zarr.create_group(store=None) - - -- a dictionary of string to :class:`Buffer ` mappings, which - will create a :ref:`memory store `. - -- an FSSpec `FSMap object `_, - which will create an :ref:`FsspecStore `. - -- a :class:`Store ` or :class:`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 -built-in store: :class:`zarr.storage.LocalStore`, :class:`zarr.storage.FsspecStore`, -:class:`zarr.storage.ZipStore`, :class:`zarr.storage.MemoryStore`, and :class:`zarr.storage.ObjectStore`. - -.. _user-guide-local-store: - -Local Store -~~~~~~~~~~~ - -The :class:`zarr.storage.LocalStore` stores data in a nested set of directories on a local -filesystem.: - - >>> store = zarr.storage.LocalStore('data/foo/bar', read_only=True) - >>> zarr.open_group(store=store, mode='r') - - -Zip Store -~~~~~~~~~ - -The :class:`zarr.storage.ZipStore` stores the contents of a Zarr hierarchy in a single -Zip file. The `Zip Store specification`_ is currently in draft form.: - - >>> store = zarr.storage.ZipStore('data.zip', mode='w') - >>> zarr.create_array(store=store, shape=(2,), dtype='float64') - - -.. _user-guide-remote-store: - -Remote Store -~~~~~~~~~~~~ - -The :class:`zarr.storage.FsspecStore` stores the contents of a Zarr hierarchy in following the same -logical layout as the ``LocalStore``, except the store is assumed to be on a remote storage system -such as cloud object storage (e.g. AWS S3, Google Cloud Storage, Azure Blob Store). The -:class:`zarr.storage.FsspecStore` is backed by `fsspec`_ and can support any backend -that implements the `AbstractFileSystem `_ -API. ``storage_options`` can be used to configure the fsspec backend.: - - >>> store = zarr.storage.FsspecStore.from_url( - ... 's3://noaa-nwm-retro-v2-zarr-pds', - ... read_only=True, - ... storage_options={'anon': True} - ... ) - >>> zarr.open_group(store=store, mode='r') - > - -The type of filesystem (e.g. S3, https, etc..) is inferred from the scheme of the url (e.g. s3 for "**s3**://noaa-nwm-retro-v2-zarr-pds"). -In case a specific filesystem is needed, one can explicitly create it. For example to create a S3 filesystem: - - >>> import fsspec - >>> fs = fsspec.filesystem( - ... 's3', anon=True, asynchronous=True, - ... client_kwargs={'endpoint_url': "https://noaa-nwm-retro-v2-zarr-pds.s3.amazonaws.com"} - ... ) - >>> store = zarr.storage.FsspecStore(fs) - -.. _user-guide-memory-store: - -Memory Store -~~~~~~~~~~~~ - -The :class:`zarr.storage.MemoryStore` a in-memory store that allows for serialization of -Zarr data (metadata and chunks) to a dictionary.: - - >>> data = {} - >>> store = zarr.storage.MemoryStore(data) - >>> # TODO: replace with create_array after #2463 - >>> zarr.create_array(store=store, shape=(2,), dtype='float64') - - -Object Store -~~~~~~~~~~~~ - -:class:`zarr.storage.ObjectStore` stores the contents of the Zarr hierarchy using any ObjectStore -`storage implementation `_, including AWS S3 (:class:`obstore.store.S3Store`), Google Cloud Storage (:class:`obstore.store.GCSStore`), and Azure Blob Storage (:class:`obstore.store.AzureStore`). This store is backed by `obstore `_, which -builds on the production quality Rust library `object_store `_. - - - >>> from zarr.storage import ObjectStore - >>> from obstore.store import MemoryStore - >>> - >>> store = ObjectStore(MemoryStore()) - >>> zarr.create_array(store=store, shape=(2,), dtype='float64') - - -Here's an example of using ObjectStore for accessing remote data: - - >>> from zarr.storage import ObjectStore - >>> from obstore.store import S3Store - >>> - >>> s3_store = S3Store('noaa-nwm-retro-v2-zarr-pds', skip_signature=True, region="us-west-2") - >>> store = zarr.storage.ObjectStore(store=s3_store, read_only=True) - >>> group = zarr.open_group(store=store, mode='r') - >>> group.info - Name : - Type : Group - Zarr format : 2 - Read-only : True - Store type : ObjectStore - No. members : 12 - No. arrays : 12 - No. groups : 0 - -.. warning:: - The :class:`zarr.storage.ObjectStore` class is experimental. - -.. _user-guide-custom-stores: - -Developing custom stores ------------------------- - -Zarr-Python :class:`zarr.abc.store.Store` API is meant to be extended. The Store Abstract Base -Class includes all of the methods needed to be a fully operational store in Zarr Python. -Zarr also provides a test harness for custom stores: :class:`zarr.testing.store.StoreTests`. - -.. _Zip Store Specification: https://github.com/zarr-developers/zarr-specs/pull/311 -.. _fsspec: https://filesystem-spec.readthedocs.io