update ci; don't save temporary files for cachestore; add doctest env

Author: d-v-b

.github/workflows/test.yml

@@ -129,11 +129,11 @@ jobs:
         pip install hatch
     - name: Set Up Hatch Env
       run: |
-        hatch env create docs
-        hatch env run -e docs list-env
+        hatch env create doctest
+        hatch env run doctest:list-env
     - name: Run Tests
       run: |
-        hatch env run --env docs check
+        hatch env run doctest:test
 
   test-complete:
     name: Test complete

docs/user-guide/experimental.md

@@ -26,12 +26,14 @@ can be any Store implementation, providing flexibility in cache persistence:
 
 ```python exec="true" session="experimental" source="above" result="ansi"
 import zarr
-import zarr.storage
+from zarr.storage import LocalStore
 import numpy as np
+from tempfile import mkdtemp
 from zarr.experimental.cache_store import CacheStore
 
 # Create a local store and a separate cache store
-source_store = zarr.storage.LocalStore('test.zarr')
+local_store_path = mkdtemp(suffix='.zarr')
+source_store = LocalStore(local_store_path)
 cache_store = zarr.storage.MemoryStore()  # In-memory cache
 cached_store = CacheStore(
     store=source_store,
@@ -63,7 +65,7 @@ for _ in range(100):
 elapsed_cache = time.time() - start
 
 # Compare with direct store access (without cache)
-zarr_array_nocache = zarr.open('test.zarr', mode='r')
+zarr_array_nocache = zarr.open(local_store_path, mode='r')
 start = time.time()
 for _ in range(100):
     _ = zarr_array_nocache[:]
@@ -75,45 +77,6 @@ speedup = elapsed_nocache / elapsed_cache
 
 Cache effectiveness is particularly pronounced with repeated access to the same data chunks.
 
-## Remote Store Caching
-
-The CacheStore is most beneficial when used with remote stores where network latency
-is a significant factor. You can use different store types for source and cache:
-
-```python
-# This example shows remote store setup but requires network access
-# from zarr.storage import FsspecStore, LocalStore
-
-# # Create a remote store (S3 example) - for demonstration only
-# remote_store = FsspecStore.from_url('s3://bucket/data.zarr', storage_options={'anon': True})
-
-# # Use a local store for persistent caching
-# local_cache_store = LocalStore('cache_data')
-
-# # Create cached store with persistent local cache
-# cached_store = CacheStore(
-#     store=remote_store,
-#     cache_store=local_cache_store,
-#     max_size=512*1024*1024  # 512MB cache
-# )
-
-# # Open array through cached store
-# z = zarr.open(cached_store)
-
-# For demonstration, use local stores instead
-from zarr.storage import LocalStore
-local_source = LocalStore('remote_data.zarr')
-local_cache = LocalStore('cache_data')
-cached_store = CacheStore(
-    store=local_source,
-    cache_store=local_cache,
-    max_size=512*1024*1024  # 512MB cache
-)
-```
-
-The first access to any chunk will be slow (network retrieval), but subsequent accesses
-to the same chunk will be served from the local cache, providing dramatic speedup.
-The cache persists between sessions when using a LocalStore for the cache backend.
 
 ## Cache Configuration
 
@@ -232,7 +195,10 @@ and use any store type for the cache backend:
 ```python exec="true" session="experimental-memory-cache" source="above" result="ansi"
 from zarr.storage import LocalStore, MemoryStore
 from zarr.experimental.cache_store import CacheStore
-source_store = LocalStore('data.zarr')
+from tempfile import mkdtemp
+
+local_store_path = mkdtemp(suffix='.zarr')
+source_store = LocalStore(local_store_path)
 cache_store = MemoryStore()
 cached_store = CacheStore(
     store=source_store,
@@ -241,40 +207,16 @@ cached_store = CacheStore(
 )
 ```
 
-### Remote Store with Local Cache
-
-```python exec="true" session="experimental-remote-cache" source="above" result="ansi"
-# Remote store example (commented out as it requires network access)
-# from zarr.storage import FsspecStore, LocalStore
-# remote_store = FsspecStore.from_url('s3://bucket/data.zarr', storage_options={'anon': True})
-# local_cache = LocalStore('local_cache')
-# cached_store = CacheStore(
-#     store=remote_store,
-#     cache_store=local_cache,
-#     max_size=1024*1024*1024,
-#     max_age_seconds=3600
-# )
-
-# Local store example for demonstration
-from zarr.storage import LocalStore
-from zarr.experimental.cache_store import CacheStore
-remote_like_store = LocalStore('remote_like_data.zarr')
-local_cache = LocalStore('local_cache')
-cached_store = CacheStore(
-    store=remote_like_store,
-    cache_store=local_cache,
-    max_size=1024*1024*1024,
-    max_age_seconds=3600
-)
-```
-
 ### Memory Store with Persistent Cache
 
 ```python exec="true" session="experimental-local-cache" source="above" result="ansi"
+from tempfile import mkdtemp
 from zarr.storage import MemoryStore, LocalStore
 from zarr.experimental.cache_store import CacheStore
+
 memory_store = MemoryStore()
-persistent_cache = LocalStore('persistent_cache')
+local_store_path = mkdtemp(suffix='.zarr')
+persistent_cache = LocalStore(local_store_path)
 cached_store = CacheStore(
     store=memory_store,
     cache_store=persistent_cache,
@@ -290,14 +232,16 @@ of source and cache stores for your specific use case.
 Here's a complete example demonstrating cache effectiveness:
 
 ```python exec="true" session="experimental-final" source="above" result="ansi"
+import numpy as np
+import time
+from tempfile import mkdtemp
 import zarr
 import zarr.storage
-import time
-import numpy as np
 from zarr.experimental.cache_store import CacheStore
 
 # Create test data with dual-store cache
-source_store = zarr.storage.LocalStore('benchmark.zarr')
+local_store_path = mkdtemp(suffix='.zarr')
+source_store = zarr.storage.LocalStore(local_store_path)
 cache_store = zarr.storage.MemoryStore()
 cached_store = CacheStore(
     store=source_store,

docs/user-guide/storage.md

@@ -23,8 +23,9 @@ group = zarr.create_group(store='data/foo/bar')
 print(group)
 ```
 
-```python exec="true" session="storage" source="above" result="ansi"
+```python
 # Implicitly create a read-only FsspecStore
+# Note: requires s3fs to be installed
 group = zarr.open_group(
    store='s3://noaa-nwm-retro-v2-zarr-pds',
    mode='r',
@@ -58,7 +59,8 @@ print(group)
    ```
 
 - an FSSpec URI string, indicating a [remote store](#remote-store) location:
-   ```python exec="true" session="storage" source="above" result="ansi"
+   ```python
+   # Note: requires s3fs to be installed
    group = zarr.open_group(
       store='s3://noaa-nwm-retro-v2-zarr-pds',
       mode='r',
@@ -124,7 +126,8 @@ 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 exec="true" session="storage" source="above" result="ansi"
+```python
+# Note: requires s3fs to be installed
 store = zarr.storage.FsspecStore.from_url(
    's3://noaa-nwm-retro-v2-zarr-pds',
    read_only=True,
@@ -137,7 +140,8 @@ 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 exec="true" session="storage" source="above" result="ansi"
+```python
+# Note: requires s3fs to be installed
 import fsspec
 fs = fsspec.filesystem(
    's3', anon=True, asynchronous=True,

pyproject.toml

@@ -257,6 +257,19 @@ check = "mkdocs build --strict"
 readthedocs = "rm -rf $READTHEDOCS_OUTPUT/html && cp -r site $READTHEDOCS_OUTPUT/html"
 list-env = "pip list"
 
+[tool.hatch.envs.doctest]
+description = "Test environment for validating executable code blocks in documentation"
+features = ['test', 'remote']  # Include remote dependencies for s3fs
+dependencies = [
+    "pytest",
+    "pytest-examples",
+]
+
+[tool.hatch.envs.doctest.scripts]
+test = "pytest tests/test_docs.py -v"
+test-file = "python tests/test_docs.py --test {args}"
+list-env = "pip list"
+
 [tool.ruff]
 line-length = 100
 force-exclude = true
@@ -396,7 +409,8 @@ addopts = [
 ]
 filterwarnings = [
     "error",
-    "ignore:Unclosed client session <aiohttp.client.ClientSession.*:ResourceWarning"
+    "ignore:Unclosed client session <aiohttp.client.ClientSession.*:ResourceWarning",
+    "ignore:Numcodecs codecs are not in the Zarr version 3 specification.*:UserWarning"
 ]
 markers = [
     "asyncio: mark test as asyncio test",