Merge main into claude/issue-161-20251029-0140

Resolved conflicts between S3 PR and FileTreeStore addition:
- Added both S3 and FileTree store to documentation
- Kept both S3 and filetree dependencies in pyproject.toml
- Updated docs to mention both stores

Co-authored-by: William Easton <[email protected]>

Author: github-actions[bot]

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.
@@ -43,6 +53,16 @@ AWS DynamoDB-backed key-value store.
       members:
         - __init__
 
+## S3 Store
+
+AWS S3-backed key-value store.
+
+::: key_value.aio.stores.s3.S3Store
+    options:
+      show_source: false
+      members:
+        - __init__
+
 ## Elasticsearch Store
 
 Elasticsearch-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.
@@ -328,6 +397,7 @@ Distributed stores provide network-based storage for multi-node applications.
 | Store | Stability | Async | Sync | Description |
 |-------|:---------:|:-----:|:----:|:------------|
 | DynamoDB | Unstable | ✅ | ✖️ | AWS DynamoDB key-value storage |
+| S3 | Unstable | ✅ | ✖️ | AWS S3 object storage |
 | Elasticsearch | Unstable | ✅ | ✅ | Full-text search with key-value capabilities |
 | Memcached | Unstable | ✅ | ✖️ | High-performance distributed memory cache |
 | MongoDB | Unstable | ✅ | ✅ | Document database used as key-value store |
@@ -434,6 +504,42 @@ pip install py-key-value-aio[dynamodb]
 
 ---
 
+### S3Store
+
+AWS S3 object storage for durable, scalable key-value storage.
+
+```python
+from key_value.aio.stores.s3 import S3Store
+
+store = S3Store(
+    bucket_name="my-kv-bucket",
+    region_name="us-east-1"
+)
+```
+
+**Installation:**
+
+```bash
+pip install py-key-value-aio[s3]
+```
+
+**Use Cases:**
+
+- Large value storage (up to 5TB per object)
+- Durable, long-term storage
+- Cost-effective archival
+- Multi-region replication
+
+**Characteristics:**
+
+- 99.999999999% durability
+- Automatic key sanitization for S3 path limits
+- Supports lifecycle policies
+- Pay-per-use pricing
+- Stable storage format: **Unstable**
+
+---
+
 ### ElasticsearchStore
 
 Full-text search engine used as a key-value store.

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"]
@@ -68,7 +69,7 @@ env_files = [".env"]
 
 [dependency-groups]
 dev = [
-    "py-key-value-aio[memory,disk,redis,elasticsearch,memcached,mongodb,vault,dynamodb,s3,rocksdb]",
+    "py-key-value-aio[memory,disk,filetree,redis,elasticsearch,memcached,mongodb,vault,dynamodb,s3,rocksdb]",
     "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/filetree/__init__.py

@@ -0,0 +1,13 @@
+"""File-tree based store for visual inspection and testing."""
+
+from key_value.aio.stores.filetree.store import (
+    FileTreeStore,
+    FileTreeV1CollectionSanitizationStrategy,
+    FileTreeV1KeySanitizationStrategy,
+)
+
+__all__ = [
+    "FileTreeStore",
+    "FileTreeV1CollectionSanitizationStrategy",
+    "FileTreeV1KeySanitizationStrategy",
+]