Merge branch 'main' into obstore-generic

Author: d-v-b

changes/3366.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/experimental#cachestore) for more information about this feature.

changes/3490.feature.md

@@ -0,0 +1 @@
+Adds a `zarr.experimental` module for unstable user-facing features.

docs/user-guide/experimental.md

@@ -0,0 +1,272 @@
+# Experimental features
+
+This section contains documentation for experimental Zarr Python features. The features described here are exciting and potentially useful, but also volatile -- we might change them at any time. Take this into account if you consider depending on these features.
+
+## `CacheStore`
+
+Zarr Python 3.1.4 adds `zarr.experimental.cache_store.CacheStore` provides a dual-store caching implementation
+that can be wrapped around any Zarr store to improve performance for repeated data access.
+This is particularly useful when working with remote stores (e.g., S3, HTTP) where network
+latency can significantly impact data access speed.
+
+The CacheStore implements a cache that uses a separate Store instance as the cache backend,
+providing persistent caching capabilities with time-based expiration, size-based eviction,
+and flexible cache storage options. It automatically evicts the least recently used items
+when the cache reaches its maximum size.
+
+Because the `CacheStore` uses an ordinary Zarr `Store` object as the caching layer, you can reuse the data stored in the cache later.
+
+> **Note:** The CacheStore is a wrapper store that maintains compatibility with the full
+> `zarr.abc.store.Store` API while adding transparent caching functionality.
+
+## Basic Usage
+
+Creating a CacheStore requires both a source store and a cache store. The cache store
+can be any Store implementation, providing flexibility in cache persistence:
+
+```python exec="true" session="experimental" source="above" result="ansi"
+import zarr
+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
+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,
+    cache_store=cache_store,
+    max_size=256*1024*1024  # 256MB cache
+)
+
+# Create an array using the cached store
+zarr_array = zarr.zeros((100, 100), chunks=(10, 10), dtype='f8', store=cached_store, mode='w')
+
+# Write some data to force chunk creation
+zarr_array[:] = np.random.random((100, 100))
+```
+
+The dual-store architecture allows you to use different store types for source and cache,
+such as a remote store for source data and a local store for persistent caching.
+
+## Performance Benefits
+
+The CacheStore provides significant performance improvements for repeated data access:
+
+```python exec="true" session="experimental" source="above" result="ansi"
+import time
+
+# Benchmark reading with cache
+start = time.time()
+for _ in range(100):
+    _ = zarr_array[:]
+elapsed_cache = time.time() - start
+
+# Compare with direct store access (without cache)
+zarr_array_nocache = zarr.open(local_store_path, mode='r')
+start = time.time()
+for _ in range(100):
+    _ = zarr_array_nocache[:]
+elapsed_nocache = time.time() - start
+
+# Cache provides speedup for repeated access
+speedup = elapsed_nocache / elapsed_cache
+```
+
+Cache effectiveness is particularly pronounced with repeated access to the same data chunks.
+
+
+## Cache Configuration
+
+The CacheStore can be configured with several parameters:
+
+**max_size**: Controls the maximum size of cached data in bytes
+
+```python exec="true" session="experimental" source="above" result="ansi"
+# 256MB cache with size limit
+cache = CacheStore(
+    store=source_store,
+    cache_store=cache_store,
+    max_size=256*1024*1024
+)
+
+# Unlimited cache size (use with caution)
+cache = CacheStore(
+    store=source_store,
+    cache_store=cache_store,
+    max_size=None
+)
+```
+
+**max_age_seconds**: Controls time-based cache expiration
+
+```python exec="true" session="experimental" source="above" result="ansi"
+# Cache expires after 1 hour
+cache = CacheStore(
+    store=source_store,
+    cache_store=cache_store,
+    max_age_seconds=3600
+)
+
+# Cache never expires
+cache = CacheStore(
+    store=source_store,
+    cache_store=cache_store,
+    max_age_seconds="infinity"
+)
+```
+
+**cache_set_data**: Controls whether written data is cached
+
+```python exec="true" session="experimental" source="above" result="ansi"
+# Cache data when writing (default)
+cache = CacheStore(
+    store=source_store,
+    cache_store=cache_store,
+    cache_set_data=True
+)
+
+# Don't cache written data (read-only cache)
+cache = CacheStore(
+    store=source_store,
+    cache_store=cache_store,
+    cache_set_data=False
+)
+```
+
+## Cache Statistics
+
+The CacheStore provides statistics to monitor cache performance and state:
+
+```python exec="true" session="experimental" source="above" result="ansi"
+# Access some data to generate cache activity
+data = zarr_array[0:50, 0:50]  # First access - cache miss
+data = zarr_array[0:50, 0:50]  # Second access - cache hit
+
+# Get comprehensive cache information
+info = cached_store.cache_info()
+print(info['cache_store_type'])  # e.g., 'MemoryStore'
+print(info['max_age_seconds'])
+print(info['max_size'])
+print(info['current_size'])
+print(info['tracked_keys'])
+print(info['cached_keys'])
+print(info['cache_set_data'])
+```
+
+The `cache_info()` method returns a dictionary with detailed information about the cache state.
+
+## Cache Management
+
+The CacheStore provides methods for manual cache management:
+
+```python exec="true" session="experimental" source="above" result="ansi"
+# Clear all cached data and tracking information
+import asyncio
+asyncio.run(cached_store.clear_cache())
+
+# Check cache info after clearing
+info = cached_store.cache_info()
+assert info['tracked_keys'] == 0
+assert info['current_size'] == 0
+```
+
+The `clear_cache()` method is an async method that clears both the cache store
+(if it supports the `clear` method) and all internal tracking data.
+
+## Best Practices
+
+1. **Choose appropriate cache store**: Use MemoryStore for fast temporary caching or LocalStore for persistent caching
+2. **Size the cache appropriately**: Set `max_size` based on available storage and expected data access patterns
+3. **Use with remote stores**: The cache provides the most benefit when wrapping slow remote stores
+4. **Monitor cache statistics**: Use `cache_info()` to tune cache size and access patterns
+5. **Consider data locality**: Group related data accesses together to improve cache efficiency
+6. **Set appropriate expiration**: Use `max_age_seconds` for time-sensitive data or "infinity" for static data
+
+## Working with Different Store Types
+
+The CacheStore can wrap any store that implements the `zarr.abc.store.Store` interface
+and use any store type for the cache backend:
+
+### Local Store with Memory Cache
+
+```python exec="true" session="experimental-memory-cache" source="above" result="ansi"
+from zarr.storage import LocalStore, MemoryStore
+from zarr.experimental.cache_store import CacheStore
+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,
+    cache_store=cache_store,
+    max_size=128*1024*1024
+)
+```
+
+### 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()
+local_store_path = mkdtemp(suffix='.zarr')
+persistent_cache = LocalStore(local_store_path)
+cached_store = CacheStore(
+    store=memory_store,
+    cache_store=persistent_cache,
+    max_size=256*1024*1024
+)
+```
+
+The dual-store architecture provides flexibility in choosing the best combination
+of source and cache stores for your specific use case.
+
+## Examples from Real Usage
+
+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
+from zarr.experimental.cache_store import CacheStore
+
+# Create test data with dual-store cache
+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,
+    cache_store=cache_store,
+    max_size=256*1024*1024
+)
+zarr_array = zarr.zeros((100, 100), chunks=(10, 10), dtype='f8', store=cached_store, mode='w')
+zarr_array[:] = np.random.random((100, 100))
+
+# Demonstrate cache effectiveness with repeated access
+start = time.time()
+data = zarr_array[20:30, 20:30]  # First access (cache miss)
+first_access = time.time() - start
+
+start = time.time()
+data = zarr_array[20:30, 20:30]  # Second access (cache hit)
+second_access = time.time() - start
+
+# Check cache statistics
+info = cached_store.cache_info()
+assert info['cached_keys'] > 0  # Should have cached keys
+assert info['current_size'] > 0  # Should have cached data
+print(f"Cache contains {info['cached_keys']} keys with {info['current_size']} bytes")
+```
+
+This example shows how the CacheStore can significantly reduce access times for repeated
+data reads, particularly important when working with remote data sources. The dual-store
+architecture allows for flexible cache persistence and management.

mkdocs.yml

@@ -25,6 +25,7 @@ nav:
       - user-guide/extending.md
       - user-guide/gpu.md
       - user-guide/consolidated_metadata.md
+      - user-guide/experimental.md
   - API Reference:
       - api/index.md
       - api/array.md

pyproject.toml

@@ -399,6 +399,7 @@ filterwarnings = [
     "ignore:Unclosed client session <aiohttp.client.ClientSession.*:ResourceWarning"
 ]
 markers = [
+    "asyncio: mark test as asyncio test",
     "gpu: mark a test as requiring CuPy and GPU",
     "slow_hypothesis: slow hypothesis tests",
 ]

src/zarr/core/dtype/npy/common.py

@@ -58,6 +58,12 @@
 IntishFloat = NewType("IntishFloat", float)
 """A type for floats that represent integers, like 1.0 (but not 1.1)."""
 
+IntishStr = NewType("IntishStr", str)
+"""A type for strings that represent integers, like "0" or "42"."""
+
+FloatishStr = NewType("FloatishStr", str)
+"""A type for strings that represent floats, like "3.14" or "-2.5"."""
+
 NumpyEndiannessStr = Literal[">", "<", "="]
 NUMPY_ENDIANNESS_STR: Final = ">", "<", "="
 
@@ -488,6 +494,59 @@ def check_json_intish_float(data: JSON) -> TypeGuard[IntishFloat]:
     return isinstance(data, float) and data.is_integer()
 
 
+def check_json_intish_str(data: JSON) -> TypeGuard[IntishStr]:
+    """
+    Check if a JSON value is a string that represents an integer, like "0", "42", or "-5".
+
+    Parameters
+    ----------
+    data : JSON
+        The JSON value to check.
+
+    Returns
+    -------
+    bool
+        True if the data is a string representing an integer, False otherwise.
+    """
+    if not isinstance(data, str):
+        return False
+
+    try:
+        int(data)
+    except ValueError:
+        return False
+    else:
+        return True
+
+
+def check_json_floatish_str(data: JSON) -> TypeGuard[FloatishStr]:
+    """
+    Check if a JSON value is a string that represents a float, like "3.14", "-2.5", or "0.0".
+
+    Note: This function is intended to be used AFTER check_json_float_v2/v3, so it only
+    handles regular string representations that those functions don't cover.
+
+    Parameters
+    ----------
+    data : JSON
+        The JSON value to check.
+
+    Returns
+    -------
+    bool
+        True if the data is a string representing a regular float, False otherwise.
+    """
+    if not isinstance(data, str):
+        return False
+
+    try:
+        float(data)
+    except ValueError:
+        return False
+    else:
+        return True
+
+
 def check_json_str(data: JSON) -> TypeGuard[str]:
     """
     Check if a JSON value is a string.

src/zarr/core/dtype/npy/float.py

@@ -19,6 +19,7 @@
     TFloatScalar_co,
     check_json_float_v2,
     check_json_float_v3,
+    check_json_floatish_str,
     endianness_to_numpy_str,
     float_from_json_v2,
     float_from_json_v3,
@@ -270,13 +271,17 @@ def from_json_scalar(self, data: JSON, *, zarr_format: ZarrFormat) -> TFloatScal
         if zarr_format == 2:
             if check_json_float_v2(data):
                 return self._cast_scalar_unchecked(float_from_json_v2(data))
+            elif check_json_floatish_str(data):
+                return self._cast_scalar_unchecked(float(data))
             else:
                 raise TypeError(
                     f"Invalid type: {data}. Expected a float or a special string encoding of a float."
                 )
         elif zarr_format == 3:
             if check_json_float_v3(data):
                 return self._cast_scalar_unchecked(float_from_json_v3(data))
+            elif check_json_floatish_str(data):
+                return self._cast_scalar_unchecked(float(data))
             else:
                 raise TypeError(
                     f"Invalid type: {data}. Expected a float or a special string encoding of a float."