chore/doctests

.github/workflows/test.yml

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

changes/3357.feature.md

@@ -0,0 +1 @@
+Adds `zarr.experimental.cache_store.CacheStore`, a `Store` that implements caching by combining two other `Store` instances. See the [docs page](https://zarr.readthedocs.io/en/latest/user-guide/cache-store) for more information about this feature.

docs/user-guide/storage.md

@@ -25,6 +25,7 @@ print(group)
 
 ```python exec="true" session="storage" source="above" result="ansi"
 # 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',
@@ -59,6 +60,7 @@ print(group)
 
 - an FSSpec URI string, indicating a [remote store](#remote-store) location:
    ```python exec="true" session="storage" source="above" result="ansi"
+   # Note: requires s3fs to be installed
    group = zarr.open_group(
       store='s3://noaa-nwm-retro-v2-zarr-pds',
       mode='r',
@@ -125,6 +127,7 @@ that implements the [AbstractFileSystem](https://filesystem-spec.readthedocs.io/
 API. `storage_options` can be used to configure the fsspec backend:
 
 ```python exec="true" session="storage" source="above" result="ansi"
+# Note: requires s3fs to be installed
 store = zarr.storage.FsspecStore.from_url(
    's3://noaa-nwm-retro-v2-zarr-pds',
    read_only=True,
@@ -138,6 +141,7 @@ The type of filesystem (e.g. S3, https, etc..) is inferred from the scheme of th
 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"
+# Note: requires s3fs to be installed
 import fsspec
 fs = fsspec.filesystem(
    's3', anon=True, asynchronous=True,

pyproject.toml

@@ -255,6 +255,18 @@ serve = "mkdocs serve"
 build = "mkdocs build"
 check = "mkdocs build --strict"
 readthedocs = "rm -rf $READTHEDOCS_OUTPUT/html && cp -r site $READTHEDOCS_OUTPUT/html"
+
+[tool.hatch.envs.doctest]
+description = "Test environment for validating executable code blocks in documentation"
+features = ['test', 'remote']  # Include remote dependencies for s3fs
+dependencies = [
+    "s3fs>=2023.10.0",
+    "pytest",
+    "pytest-examples",
+]
+
+[tool.hatch.envs.doctest.scripts]
+test = "pytest tests/test_docs.py -v"
 list-env = "pip list"
 
 [tool.ruff]
@@ -396,7 +408,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",

src/zarr/experimental/cache_store.py

@@ -109,7 +109,6 @@ def __init__(
             self.key_insert_times = {}
         else:
             self.key_insert_times = key_insert_times
-
         self.cache_set_data = cache_set_data
         self._cache_order = OrderedDict()
         self._current_size = 0

tests/test_docs.py

@@ -0,0 +1,108 @@
+"""
+Tests for executable code blocks in markdown documentation.
+
+This module uses pytest-examples to validate that all Python code examples
+with exec="true" in the documentation execute successfully.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from pathlib import Path
+
+import pytest
+
+pytest_examples = pytest.importorskip("pytest_examples")
+
+# Find all markdown files with executable code blocks
+docs_root = Path(__file__).parent.parent / "docs"
+
+
+def find_markdown_files_with_exec() -> list[Path]:
+    """Find all markdown files containing exec="true" code blocks."""
+    markdown_files = []
+
+    for md_file in docs_root.rglob("*.md"):
+        try:
+            content = md_file.read_text(encoding="utf-8")
+            if 'exec="true"' in content:
+                markdown_files.append(md_file)
+        except Exception:
+            # Skip files that can't be read
+            continue
+
+    return sorted(markdown_files)
+
+
+def group_examples_by_session() -> list[tuple[str, str]]:
+    """
+    Group examples by their session and file, maintaining order.
+
+    Returns a list of session_key tuples where session_key is
+    (file_path, session_name).
+    """
+    all_examples = list(pytest_examples.find_examples(docs_root))
+
+    # Group by file and session
+    sessions = defaultdict(list)
+
+    for example in all_examples:
+        settings = example.prefix_settings()
+        if settings.get("exec") != "true":
+            continue
+
+        # Use file path and session name as key
+        file_path = example.path
+        session_name = settings.get("session", "_default")
+        session_key = (str(file_path), session_name)
+
+        sessions[session_key].append(example)
+
+    # Return sorted list of session keys for consistent test ordering
+    return sorted(sessions.keys(), key=lambda x: (x[0], x[1]))
+
+
+def name_example(path: str, session: str) -> str:
+    """Generate a readable name for a test case from file path and session."""
+    return f"{Path(path).relative_to(docs_root)}:{session}"
+
+
+# Get all example sessions
+@pytest.mark.parametrize(
+    "session_key", group_examples_by_session(), ids=lambda v: name_example(v[0], v[1])
+)
+def test_documentation_examples(
+    session_key: tuple[str, str],
+    eval_example: pytest_examples.EvalExample,  # type: ignore[name-defined]
+) -> None:
+    """
+    Test that all exec="true" code examples in documentation execute successfully.
+
+    This test groups examples by session (file + session name) and runs them
+    sequentially in the same execution context, allowing code to build on
+    previous examples.
+
+    This test uses pytest-examples to:
+    - Find all code examples with exec="true" in markdown files
+    - Group them by session
+    - Execute them in order within the same context
+    - Verify no exceptions are raised
+    """
+    file_path, session_name = session_key
+
+    # Get examples for this session
+    all_examples = list(pytest_examples.find_examples(docs_root))
+    examples = []
+    for example in all_examples:
+        settings = example.prefix_settings()
+        if settings.get("exec") != "true":
+            continue
+        if str(example.path) == file_path and settings.get("session", "_default") == session_name:
+            examples.append(example)
+
+    # Run all examples in this session sequentially, preserving state
+    module_globals: dict[str, object] = {}
+    for example in examples:
+        result = eval_example.run(example, module_globals=module_globals)
+        # Update globals with the results from this execution
+        module_globals.update(result)