Add AWS S3 Store

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"]
@@ -70,7 +71,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/dynamodb/store.py

@@ -40,6 +40,7 @@ class DynamoDBStore(BaseContextManagerStore, BaseStore):
     _endpoint_url: str | None
     _raw_client: Any  # DynamoDB client from aioboto3
     _client: DynamoDBClient | None
+    _owns_client: bool
 
     @overload
     def __init__(self, *, client: DynamoDBClient, table_name: str, default_collection: str | None = None) -> None:
@@ -101,6 +102,8 @@ def __init__(
         self._table_name = table_name
         if client:
             self._client = client
+            self._raw_client = None
+            self._owns_client = False
         else:
             session: Session = aioboto3.Session(
                 region_name=region_name,
@@ -112,6 +115,7 @@ def __init__(
             self._raw_client = session.client(service_name="dynamodb", endpoint_url=endpoint_url)  # pyright: ignore[reportUnknownMemberType]
 
             self._client = None
+            self._owns_client = True
 
         super().__init__(default_collection=default_collection)
 
@@ -127,8 +131,8 @@ async def __aexit__(
         self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
     ) -> None:
         await super().__aexit__(exc_type, exc_value, traceback)
-        if self._client:
-            await self._client.__aexit__(exc_type, exc_value, traceback)
+        if self._owns_client and self._raw_client:
+            await self._raw_client.__aexit__(exc_type, exc_value, traceback)
 
     @property
     def _connected_client(self) -> DynamoDBClient:
@@ -256,5 +260,5 @@ async def _delete_managed_entry(self, *, key: str, collection: str) -> bool:
     @override
     async def _close(self) -> None:
         """Close the DynamoDB client."""
-        if self._client:
-            await self._client.__aexit__(None, None, None)  # pyright: ignore[reportUnknownMemberType]
+        if self._owns_client and self._raw_client:
+            await self._raw_client.__aexit__(None, None, None)  # pyright: ignore[reportUnknownMemberType]

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",
+]