Executable storage guide

Author: maxrjones

docs/user-guide/storage.md

@@ -14,25 +14,29 @@ Zarr-Python 3, stores must implement the abstract store API from
 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:
 
-```python
+```python exec="true" session="storage" source="above" result="ansi"
 import zarr
 
 # Implicitly create a writable LocalStore
-zarr.create_group(store='data/foo/bar')
-# <Group file://data/foo/bar>
+group = zarr.create_group(store='data/foo/bar')
+print(group)
+```
 
+```python exec="true" session="storage" source="above" result="ansi"
 # Implicitly create a read-only FsspecStore
-zarr.open_group(
+group = zarr.open_group(
    store='s3://noaa-nwm-retro-v2-zarr-pds',
    mode='r',
    storage_options={'anon': True}
 )
-# <Group <FsspecStore(S3FileSystem, noaa-nwm-retro-v2-zarr-pds)>>
+print(group)
+```
 
+```python exec="true" session="storage" source="above" result="ansi"
 # Implicitly creates a MemoryStore
 data = {}
-zarr.create_group(store=data)
-# <Group memory://...>
+group = zarr.create_group(store=data)
+print(group)
 ```
 
 ## Explicit Store Creation
@@ -46,21 +50,21 @@ built-in store: [`zarr.storage.LocalStore`][], [`zarr.storage.FsspecStore`][],
 The [`zarr.storage.LocalStore`][] stores data in a nested set of directories on a local
 filesystem:
 
-```python
+```python exec="true" session="storage" source="above" result="ansi"
 store = zarr.storage.LocalStore('data/foo/bar', read_only=True)
-zarr.open_group(store=store, mode='r')
-# <Group file://data/foo/bar>
+group = zarr.open_group(store=store, mode='r')
+print(group)
 ```
 
 ### Zip Store
 
 The [`zarr.storage.ZipStore`][] stores the contents of a Zarr hierarchy in a single
 Zip file. The [Zip Store specification](https://github.com/zarr-developers/zarr-specs/pull/311) is currently in draft form:
 
-```python
+```python exec="true" session="storage" source="above" result="ansi"
 store = zarr.storage.ZipStore('data.zip', mode='w')
-zarr.create_array(store=store, shape=(2,), dtype='float64')
-# <Array zip://data.zip shape=(2,) dtype=float64>
+array = zarr.create_array(store=store, shape=(2,), dtype='float64')
+print(array)
 ```
 
 ### Remote Store
@@ -72,26 +76,27 @@ such as cloud object storage (e.g. AWS S3, Google Cloud Storage, Azure Blob Stor
 that implements the [AbstractFileSystem](https://filesystem-spec.readthedocs.io/en/stable/api.html#fsspec.spec.AbstractFileSystem)
 API. `storage_options` can be used to configure the fsspec backend:
 
-```python
+```python exec="true" session="storage" source="above" result="ansi"
 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')
-# <Group <FsspecStore(S3FileSystem, noaa-nwm-retro-v2-zarr-pds)>>
+group = zarr.open_group(store=store, mode='r')
+print(group)
 ```
 
 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:
 
-```python
+```python exec="true" session="storage" source="above" result="ansi"
 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)
+print(store)
 ```
 
 
@@ -100,12 +105,11 @@ store = zarr.storage.FsspecStore(fs)
 The [`zarr.storage.MemoryStore`][] a in-memory store that allows for serialization of
 Zarr data (metadata and chunks) to a dictionary:
 
-```python
+```python exec="true" session="storage" source="above" result="ansi"
 data = {}
 store = zarr.storage.MemoryStore(data)
-# TODO: replace with create_array after #2463
-zarr.create_array(store=store, shape=(2,), dtype='float64')
-# <Array memory://... shape=(2,) dtype=float64>
+array = zarr.create_array(store=store, shape=(2,), dtype='float64')
+print(array)
 ```
 
 ### Object Store
@@ -114,33 +118,25 @@ zarr.create_array(store=store, shape=(2,), dtype='float64')
 [storage implementation](https://developmentseed.org/obstore/latest/api/store/), including AWS S3 ([`obstore.store.S3Store`][]), Google Cloud Storage ([`obstore.store.GCSStore`][]), and Azure Blob Storage ([`obstore.store.AzureStore`][]). This store is backed by [obstore](https://developmentseed.org/obstore/latest/), which
 builds on the production quality Rust library [object_store](https://docs.rs/object_store/latest/object_store/).
 
-```python
+```python exec="true" session="storage" source="above" result="ansi"
 from zarr.storage import ObjectStore
 from obstore.store import MemoryStore
 
 store = ObjectStore(MemoryStore())
-zarr.create_array(store=store, shape=(2,), dtype='float64')
-# <Array object_store://... shape=(2,) dtype=float64>
+array = zarr.create_array(store=store, shape=(2,), dtype='float64')
+print(array)
 ```
 
 Here's an example of using ObjectStore for accessing remote data:
 
-```python
+```python exec="true" session="storage" source="above" result="ansi"
 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
+print(group.info)
 ```
 
 !!! warning

pyproject.toml

@@ -252,7 +252,7 @@ fix = "rm -r data/; pytest docs/user-guide --doctest-glob='*.rst' --accept"
 list-env = "pip list"
 
 [tool.hatch.envs.docs]
-features = ['docs']
+features = ['docs', 'remote']
 
 [tool.hatch.envs.docs.scripts]
 serve = "mkdocs serve"