Add AWS S3

README.md

@@ -17,7 +17,7 @@ This monorepo contains two libraries:
 
 ## Why use this library?
 
-- **Multiple backends**: DynamoDB, Elasticsearch, Memcached, MongoDB, Redis,
+- **Multiple backends**: DynamoDB, S3, Elasticsearch, Memcached, MongoDB, Redis,
   RocksDB, Valkey, and In-memory, Disk, etc
 - **TTL support**: Automatic expiration handling across all store types
 - **Type-safe**: Full type hints with Protocol-based interfaces
@@ -131,6 +131,7 @@ pip install py-key-value-aio
 pip install py-key-value-aio[memory]
 pip install py-key-value-aio[disk]
 pip install py-key-value-aio[dynamodb]
+pip install py-key-value-aio[s3]
 pip install py-key-value-aio[elasticsearch]
 # or: redis, mongodb, memcached, valkey, vault, registry, rocksdb, see below for all options
 ```
@@ -191,7 +192,7 @@ categories:
 - **Local stores**: In-memory and disk-based storage (Memory, Disk, RocksDB, etc.)
 - **Secret stores**: Secure OS-level storage for sensitive data (Keyring, Vault)
 - **Distributed stores**: Network-based storage for multi-node apps (Redis,
-  DynamoDB, MongoDB, etc.)
+  DynamoDB, S3, MongoDB, etc.)
 
 Each store has a **stability rating** indicating likelihood of
 backwards-incompatible changes. Stable stores (Redis, Valkey, Disk, Keyring)

docs/api/stores.md

@@ -53,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

@@ -397,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 |
@@ -503,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

@@ -42,6 +42,7 @@ vault = ["hvac>=2.3.0", "types-hvac>=2.3.0"]
 memcached = ["aiomcache>=0.8.0"]
 elasticsearch = ["elasticsearch>=8.0.0", "aiohttp>=3.12"]
 dynamodb = ["aioboto3>=13.3.0", "types-aiobotocore-dynamodb>=2.16.0"]
+s3 = ["aioboto3>=13.3.0", "types-aiobotocore-s3>=2.16.0"]
 keyring = ["keyring>=25.6.0"]
 keyring-linux = ["keyring>=25.6.0", "dbus-python>=1.4.0"]
 pydantic = ["pydantic>=2.11.9"]
@@ -69,7 +70,7 @@ env_files = [".env"]
 
 [dependency-groups]
 dev = [
-    "py-key-value-aio[memory,disk,filetree,redis,elasticsearch,memcached,mongodb,vault,dynamodb,rocksdb,duckdb]",
+    "py-key-value-aio[memory,disk,filetree,redis,elasticsearch,memcached,mongodb,vault,dynamodb,s3,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/elasticsearch/store.py

@@ -268,7 +268,7 @@ async def _setup_collection(self, *, collection: str) -> None:
         try:
             _ = await self._client.options(ignore_status=404).indices.create(index=index_name, mappings=DEFAULT_MAPPING, settings={})
         except BadRequestError as e:
-            if "index_already_exists_exception" in str(e).lower():
+            if "already_exists_exception" in str(e).lower():
                 return
             raise
 

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

@@ -0,0 +1,13 @@
+"""AWS S3-based key-value store."""
+
+from key_value.aio.stores.s3.store import (
+    S3CollectionSanitizationStrategy,
+    S3KeySanitizationStrategy,
+    S3Store,
+)
+
+__all__ = [
+    "S3CollectionSanitizationStrategy",
+    "S3KeySanitizationStrategy",
+    "S3Store",
+]