codex changes

Author: shaypal5

README.rst

@@ -59,6 +59,7 @@ Current features
   * Cross-machine caching using MongoDB.
   * SQL-based caching using SQLAlchemy-supported databases.
   * Redis-based caching for high-performance scenarios.
+  * S3-based caching for cross-machine object storage backends.
 
 * Thread-safety.
 * **Per-call max age:** Specify a maximum age for cached values per call.
@@ -71,7 +72,6 @@ Cachier is **NOT**:
 Future features
 ---------------
 
-* S3 core.
 * Multi-core caching.
 * `Cache replacement policies <https://en.wikipedia.org/wiki/Cache_replacement_policies>`_
 
@@ -580,6 +580,12 @@ Cachier supports Redis-based caching for high-performance scenarios. Redis provi
 - ``processing``: Boolean, is value being calculated
 - ``completed``: Boolean, is value calculation completed
 
+**S3 Sync/Async Support:**
+
+- Sync functions use direct boto3 calls.
+- Async functions are supported via thread-offloaded sync boto3 calls
+  (delegated mode), not a native async client.
+
 **Limitations & Notes:**
 
 - Requires SQLAlchemy (install with ``pip install SQLAlchemy``)
@@ -631,6 +637,11 @@ async drivers and require the client or engine type to match the decorated funct
      - ``redis_client`` must be a sync client or sync callable for sync functions and
        an async callable returning a ``redis.asyncio.Redis`` client for async
        functions. Passing a sync callable to an async function raises ``TypeError``.
+   * - **S3**
+     - Yes
+     - Yes (delegated)
+     - Async support is delegated via thread-offloaded sync boto3 calls
+       (``asyncio.to_thread``). No async S3 client is required.
 
 
 Contributing
@@ -655,13 +666,14 @@ Install in development mode with test dependencies for local cores (memory and p
   cd cachier
   pip install -e . -r tests/requirements.txt
 
-Each additional core (MongoDB, Redis, SQL) requires additional dependencies. To install all dependencies for all cores, run:
+Each additional core (MongoDB, Redis, SQL, S3) requires additional dependencies. To install all dependencies for all cores, run:
 
 .. code-block:: bash
 
   pip install -r tests/requirements_mongodb.txt
   pip install -r tests/requirements_redis.txt
   pip install -r tests/requirements_postgres.txt
+  pip install -r tests/requirements_s3.txt
 
 Running the tests
 -----------------

src/cachier/cores/s3.py

@@ -1,5 +1,6 @@
 """An S3-based caching core for cachier."""
 
+import asyncio
 import pickle
 import time
 import warnings
@@ -28,6 +29,10 @@ class MissingS3Bucket(ValueError):
 class _S3Core(_BaseCore):
     """S3-based core for Cachier, supporting AWS S3 and S3-compatible backends.
 
+    Async support in this core is delegated rather than native. Since boto3 is a
+    synchronous client, async methods explicitly offload I/O work to a thread via
+    ``asyncio.to_thread``.
+
     Parameters
     ----------
     hash_func : callable, optional
@@ -367,6 +372,51 @@ def delete_stale_entries(self, stale_after: timedelta) -> None:
             warnings.warn(f"S3 delete_stale_entries failed: {exc}", stacklevel=2)
 
     # ------------------------------------------------------------------
-    # Async variants delegate to the thread-based defaults in _BaseCore
-    # since boto3 is a sync library.
+    # Async variants explicitly offload sync boto3 operations to avoid
+    # blocking the event loop thread.
     # ------------------------------------------------------------------
+
+    async def aget_entry(self, args, kwds) -> Tuple[str, Optional[CacheEntry]]:
+        """Async-compatible variant of :meth:`get_entry`.
+
+        This method delegates to the sync implementation via
+        ``asyncio.to_thread`` because boto3 is sync-only.
+
+        """
+        return await asyncio.to_thread(self.get_entry, args, kwds)
+
+    async def aget_entry_by_key(self, key: str) -> Tuple[str, Optional[CacheEntry]]:
+        """Async-compatible variant of :meth:`get_entry_by_key`.
+
+        This method delegates to the sync implementation via
+        ``asyncio.to_thread`` because boto3 is sync-only.
+
+        """
+        return await asyncio.to_thread(self.get_entry_by_key, key)
+
+    async def aset_entry(self, key: str, func_res: Any) -> bool:
+        """Async-compatible variant of :meth:`set_entry`.
+
+        This method delegates to the sync implementation via
+        ``asyncio.to_thread`` because boto3 is sync-only.
+
+        """
+        return await asyncio.to_thread(self.set_entry, key, func_res)
+
+    async def amark_entry_being_calculated(self, key: str) -> None:
+        """Async-compatible variant of :meth:`mark_entry_being_calculated`.
+
+        This method delegates to the sync implementation via
+        ``asyncio.to_thread`` because boto3 is sync-only.
+
+        """
+        await asyncio.to_thread(self.mark_entry_being_calculated, key)
+
+    async def amark_entry_not_calculated(self, key: str) -> None:
+        """Async-compatible variant of :meth:`mark_entry_not_calculated`.
+
+        This method delegates to the sync implementation via
+        ``asyncio.to_thread`` because boto3 is sync-only.
+
+        """
+        await asyncio.to_thread(self.mark_entry_not_calculated, key)