feat: support providing a path prefix to S3 storage (#342)

* feat: support providing path prefix to S3 storage

* Add CHANGELOG.md entry

---------

Co-authored-by: Zygimantas Straznickas <zygi@anthropic.com>

Author: zygi

CHANGELOG.md

@@ -5,6 +5,7 @@
 - Remove `types-redis` from dev dependencies (#336)
 - Bump redis to 6.0.0 and address async `.close()` deprecation warning (#336)
 - Avoid race condition when unlinking files in `FileStorage`. (#334)  
+- Allow prodiving a `path_prefix` in `S3Storage` and `AsyncS3Storage`. (#342)
 
 ## 0.1.2 (5th April, 2025)
 

hishel/_async/_storages.py

@@ -654,6 +654,8 @@ class AsyncS3Storage(AsyncBaseStorage):  # pragma: no cover
     :type check_ttl_every: tp.Union[int, float]
     :param client: A client for S3, defaults to None
     :type client: tp.Optional[tp.Any], optional
+    :param path_prefix: A path prefix to use for S3 object keys, defaults to "hishel-"
+    :type path_prefix: str, optional
     """
 
     def __init__(
@@ -663,6 +665,7 @@ def __init__(
         ttl: tp.Optional[tp.Union[int, float]] = None,
         check_ttl_every: tp.Union[int, float] = 60,
         client: tp.Optional[tp.Any] = None,
+        path_prefix: str = "hishel-",
     ) -> None:
         super().__init__(serializer, ttl)
 
@@ -680,6 +683,7 @@ def __init__(
             bucket_name=bucket_name,
             is_binary=self._serializer.is_binary,
             check_ttl_every=check_ttl_every,
+            path_prefix=path_prefix,
         )
         self._lock = AsyncLock()
 

hishel/_s3.py

@@ -11,16 +11,22 @@ def get_timestamp_in_ms() -> float:
 
 class S3Manager:
     def __init__(
-        self, client: tp.Any, bucket_name: str, check_ttl_every: tp.Union[int, float], is_binary: bool = False
+        self,
+        client: tp.Any,
+        bucket_name: str,
+        check_ttl_every: tp.Union[int, float],
+        is_binary: bool = False,
+        path_prefix: str = "hishel-",
     ):
         self._client = client
         self._bucket_name = bucket_name
         self._is_binary = is_binary
         self._last_cleaned = time.monotonic()
         self._check_ttl_every = check_ttl_every
+        self._path_prefix = path_prefix
 
     def write_to(self, path: str, data: tp.Union[bytes, str], only_metadata: bool = False) -> None:
-        path = "hishel-" + path
+        path = self._path_prefix + path
         if isinstance(data, str):
             data = data.encode("utf-8")
 
@@ -43,7 +49,7 @@ def write_to(self, path: str, data: tp.Union[bytes, str], only_metadata: bool =
         )
 
     def read_from(self, path: str) -> tp.Union[bytes, str]:
-        path = "hishel-" + path
+        path = self._path_prefix + path
         response = self._client.get_object(
             Bucket=self._bucket_name,
             Key=path,
@@ -57,7 +63,7 @@ def read_from(self, path: str) -> tp.Union[bytes, str]:
         return tp.cast(str, content.decode("utf-8"))
 
     def remove_expired(self, ttl: int, key: str) -> None:
-        path = "hishel-" + key
+        path = self._path_prefix + key
 
         if time.monotonic() - self._last_cleaned < self._check_ttl_every:
             try:
@@ -72,7 +78,7 @@ def remove_expired(self, ttl: int, key: str) -> None:
 
         self._last_cleaned = time.monotonic()
         for obj in self._client.list_objects(Bucket=self._bucket_name).get("Contents", []):
-            if not obj["Key"].startswith("hishel-"):  # pragma: no cover
+            if not obj["Key"].startswith(self._path_prefix):  # pragma: no cover
                 continue
 
             try:
@@ -88,15 +94,20 @@ def remove_expired(self, ttl: int, key: str) -> None:
                 self._client.delete_object(Bucket=self._bucket_name, Key=obj["Key"])
 
     def remove_entry(self, key: str) -> None:
-        path = "hishel-" + key
+        path = self._path_prefix + key
         self._client.delete_object(Bucket=self._bucket_name, Key=path)
 
 
 class AsyncS3Manager:  # pragma: no cover
     def __init__(
-        self, client: tp.Any, bucket_name: str, check_ttl_every: tp.Union[int, float], is_binary: bool = False
+        self,
+        client: tp.Any,
+        bucket_name: str,
+        check_ttl_every: tp.Union[int, float],
+        is_binary: bool = False,
+        path_prefix: str = "hishel-",
     ):
-        self._sync_manager = S3Manager(client, bucket_name, check_ttl_every, is_binary)
+        self._sync_manager = S3Manager(client, bucket_name, check_ttl_every, is_binary, path_prefix)
 
     async def write_to(self, path: str, data: tp.Union[bytes, str], only_metadata: bool = False) -> None:
         return await to_thread.run_sync(self._sync_manager.write_to, path, data, only_metadata)

hishel/_sync/_storages.py

@@ -654,6 +654,8 @@ class S3Storage(BaseStorage):  # pragma: no cover
     :type check_ttl_every: tp.Union[int, float]
     :param client: A client for S3, defaults to None
     :type client: tp.Optional[tp.Any], optional
+    :param path_prefix: A path prefix to use for S3 object keys, defaults to "hishel-"
+    :type path_prefix: str, optional
     """
 
     def __init__(
@@ -663,6 +665,7 @@ def __init__(
         ttl: tp.Optional[tp.Union[int, float]] = None,
         check_ttl_every: tp.Union[int, float] = 60,
         client: tp.Optional[tp.Any] = None,
+        path_prefix: str = "hishel-",
     ) -> None:
         super().__init__(serializer, ttl)
 
@@ -680,6 +683,7 @@ def __init__(
             bucket_name=bucket_name,
             is_binary=self._serializer.is_binary,
             check_ttl_every=check_ttl_every,
+            path_prefix=path_prefix,
         )
         self._lock = Lock()