Merge branch 'main' into claude/issue-187-20251101-1758

Author: strawgate

docs/api/stores.md

@@ -23,6 +23,16 @@ Persistent disk-based key-value store using DiskCache.
       members:
         - __init__
 
+## FileTree Store
+
+Directory-based store for visual inspection and testing.
+
+::: key_value.aio.stores.filetree.FileTreeStore
+    options:
+      show_source: false
+      members:
+        - __init__
+
 ## Redis Store
 
 Redis-backed key-value store.

docs/stores.md

@@ -34,6 +34,7 @@ Local stores are stored in memory or on disk, local to the application.
 | Memory | N/A | ✅ | ✅ | Fast in-memory storage for development and caching |
 | Disk | Stable | ☑️ | ✅ | Persistent file-based storage in a single file |
 | Disk (Per-Collection) | Stable | ☑️ | ✅ | Persistent storage with separate files per collection |
+| FileTree (test) | Unstable | ☑️ | ✅ | Directory-based storage with JSON files for visual inspection |
 | Null (test) | N/A | ✅ | ✅ | No-op store for testing without side effects |
 | RocksDB | Unstable | ☑️ | ✅ | High-performance embedded database |
 | Simple (test) | N/A | ✅ | ✅ | Simple in-memory store for testing |
@@ -140,6 +141,74 @@ pip install py-key-value-aio[disk]
 
 ---
 
+### FileTreeStore
+
+Directory-based storage for visual inspection and debugging.
+
+```python
+from key_value.aio.stores.filetree import FileTreeStore
+
+store = FileTreeStore(directory="./debug-store")
+```
+
+**Installation:**
+
+```bash
+pip install py-key-value-aio[filetree]
+```
+
+**Use Cases:**
+
+- Visual inspection of store contents
+- Debugging store behavior
+- Development and testing
+- Understanding data structure
+
+**Characteristics:**
+
+- Collections as directories
+- Keys as JSON files (`{key}.json`)
+- Human-readable filesystem layout
+- Easy to inspect and modify
+- **NOT for production use**
+
+**Directory Structure:**
+
+```text
+{base_directory}/
+  {collection_1}/
+    {key_1}.json
+    {key_2}.json
+  {collection_2}/
+    {key_3}.json
+```
+
+**Important Limitations:**
+
+- Poor performance with many keys
+- No atomic operations
+- No automatic cleanup of expired entries
+- Filesystem path length constraints
+- Subject to filesystem limitations
+
+**When to Use:**
+
+Use FileTreeStore when you need to:
+
+- Visually inspect what's being stored
+- Debug complex data structures
+- Understand how the store organizes data
+- Manually modify stored data for testing
+
+**When NOT to Use:**
+
+- Production environments
+- High-performance requirements
+- Large datasets
+- Concurrent access scenarios
+
+---
+
 ### RocksDBStore
 
 High-performance embedded database using RocksDB.

key-value/key-value-aio/pyproject.toml

@@ -34,6 +34,7 @@ py-key-value-shared-test = { workspace = true }
 [project.optional-dependencies]
 memory = ["cachetools>=5.0.0"]
 disk = ["diskcache>=5.0.0", "pathvalidate>=3.3.1",]
+filetree = ["aiofile>=3.5.0", "anyio>=4.4.0"]
 redis = ["redis>=4.3.0"]
 mongodb = ["pymongo>=4.0.0"]
 valkey = ["valkey-glide>=2.1.0"]
@@ -48,6 +49,7 @@ rocksdb = [
     "rocksdict>=0.3.24 ; python_version >= '3.12'", # RocksDB 0.3.24 is the first version to support Python 3.13
     "rocksdict>=0.3.2 ; python_version < '3.12'"
 ]
+duckdb = ["duckdb>=1.1.1", "pytz>=2025.2"]
 wrappers-encryption = ["cryptography>=45.0.0"]
 
 [tool.pytest.ini_options]
@@ -67,7 +69,7 @@ env_files = [".env"]
 
 [dependency-groups]
 dev = [
-    "py-key-value-aio[memory,disk,redis,elasticsearch,memcached,mongodb,vault,dynamodb,rocksdb]",
+    "py-key-value-aio[memory,disk,filetree,redis,elasticsearch,memcached,mongodb,vault,dynamodb,rocksdb,duckdb]",
     "py-key-value-aio[valkey]; platform_system != 'Windows'",
     "py-key-value-aio[keyring]",
     "py-key-value-aio[pydantic]",

key-value/key-value-aio/src/key_value/aio/stores/duckdb/__init__.py

@@ -0,0 +1,3 @@
+from key_value.aio.stores.duckdb.store import DuckDBStore
+
+__all__ = ["DuckDBStore"]