fallbacks3 0.3.1__tar.gz → 0.5.0__tar.gz

{fallbacks3-0.3.1 → fallbacks3-0.5.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: fallbacks3
-Version: 0.3.1
+Version: 0.5.0
 Summary: S3-compatible storage library with automatic fallback support
 Author-email: Mila de Oliveira <mila.oliveira@palver.com.br>
 Project-URL: Homepage, https://github.com/palverdata/fallbacks3
 Project-URL: Repository, https://github.com/palverdata/fallbacks3
 Project-URL: Issues, https://github.com/palverdata/fallbacks3/issues
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: boto3>=1.26.0
 Requires-Dist: pydantic-settings>=2.0.0
@@ -49,6 +49,15 @@ PROVIDERS="ps3://access_key:secret_key@ps3.palver.com,r2://access_key:secret_key
 FALLBACK_PROVIDER="r2"
 ```
 
+`FALLBACK_PROVIDER` may also be set as a `<scheme>://<bucket>` URI to redirect fallback
+uploads to a specific bucket instead of reusing the original request's bucket. The scheme
+must still be one of the providers in `PROVIDERS`.
+
+```bash
+# On fallback, upload to bucket "bucket-v2" on the r2 provider
+FALLBACK_PROVIDER="r2://bucket-v2"
+```
+
 
 ### Provider URI Format
 
@@ -108,7 +117,7 @@ print(signed_url)  # "https://ps3.palver.com/palver-whatsapp/audio.mp3?signature
 
 ### Upload with Automatic Fallback
 
-If the primary provider fails for the upload method, the library automatically retries with the fallback provider (using the same bucket and file path), as to ensure files are not lost.
+If the primary provider fails for the upload method, the library automatically retries with the fallback provider (using the same bucket and file path, unless `FALLBACK_PROVIDER` specifies a bucket), as to ensure files are not lost.
 
 ```python
 # If ps3 fails, automatically falls back to r2

{fallbacks3-0.3.1 → fallbacks3-0.5.0}/README.md

@@ -28,6 +28,15 @@ PROVIDERS="ps3://access_key:secret_key@ps3.palver.com,r2://access_key:secret_key
 FALLBACK_PROVIDER="r2"
 ```
 
+`FALLBACK_PROVIDER` may also be set as a `<scheme>://<bucket>` URI to redirect fallback
+uploads to a specific bucket instead of reusing the original request's bucket. The scheme
+must still be one of the providers in `PROVIDERS`.
+
+```bash
+# On fallback, upload to bucket "bucket-v2" on the r2 provider
+FALLBACK_PROVIDER="r2://bucket-v2"
+```
+
 
 ### Provider URI Format
 
@@ -87,7 +96,7 @@ print(signed_url)  # "https://ps3.palver.com/palver-whatsapp/audio.mp3?signature
 
 ### Upload with Automatic Fallback
 
-If the primary provider fails for the upload method, the library automatically retries with the fallback provider (using the same bucket and file path), as to ensure files are not lost.
+If the primary provider fails for the upload method, the library automatically retries with the fallback provider (using the same bucket and file path, unless `FALLBACK_PROVIDER` specifies a bucket), as to ensure files are not lost.
 
 ```python
 # If ps3 fails, automatically falls back to r2

{fallbacks3-0.3.1 → fallbacks3-0.5.0}/fallbacks3/provider/provider.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
-
 from boto3 import client
+from boto3.s3.transfer import TransferConfig
 from botocore.client import Config as BotoConfig
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from mypy_boto3_s3.client import S3Client
@@ -18,6 +18,7 @@ class S3Provider:
         endpoint: str,
         access_key_id: str,
         secret_access_key: str,
+        transfer_config: TransferConfig | None = None,
     ):
         """Initialize S3 provider with credentials.
 
@@ -26,9 +27,12 @@ class S3Provider:
             endpoint: S3 endpoint URL with scheme (e.g., 'https://ps3.palver.com')
             access_key_id: Access key ID
             secret_access_key: Secret access key
+            transfer_config: Optional boto3 TransferConfig for upload behaviour.
+                Defaults to boto3's built-in defaults when None.
         """
         self.provider_scheme: str = provider_scheme
         self.endpoint: str = endpoint
+        self.transfer_config: TransferConfig | None = transfer_config
         self.client: S3Client = client(
             "s3",
             config=BotoConfig(signature_version="s3v4"),
@@ -49,7 +53,11 @@ class S3Provider:
             Full URI of the uploaded file in format:
             <provider_scheme>://<bucket>/<file_name>
         """
-        self.client.upload_file(file_path, bucket, file_name)
+        self.client.upload_file(
+            file_path, bucket, file_name, Config=self.transfer_config
+        ) if self.transfer_config else self.client.upload_file(
+            file_path, bucket, file_name
+        )
         return f"{self.provider_scheme}://{bucket}/{file_name}"
 
     def download_file(self, file_name: str, local_path: str, bucket: str) -> str:

{fallbacks3-0.3.1 → fallbacks3-0.5.0}/fallbacks3/storage.py

@@ -1,4 +1,5 @@
 import asyncio
+
 from fallbacks3.config import config
 from fallbacks3.provider import S3Provider
 from fallbacks3.utils.uri import build_provider_credentials, parse_uri
@@ -12,6 +13,7 @@ class Storage:
         self,
         providers: str = config.providers,
         fallback_provider: str = config.fallback_provider,
+        provider_configs: dict[str, dict] | None = None,
     ):
         """Initialize storage with multiple providers.
 
@@ -20,9 +22,15 @@ class Storage:
                 <provider>://<access_key>:<secret_key>@<endpoint>
                 Example: "ps3://key:secret@ps3.palver.com,s4://a:b@s4.mega.com"
                 Defaults to PROVIDERS environment variable.
-            fallback_provider: Provider scheme to use for fallback (e.g., "r2").
-                Must be one of the providers in the providers string.
+            fallback_provider: Fallback provider to use on upload failure. Either
+                a bare scheme (e.g. "r2"), which reuses the original bucket, or a
+                "<scheme>://<bucket>" URI (e.g. "r2://bucket-v2"), which redirects
+                fallback uploads to <bucket>. The scheme must be one of the
+                providers in the providers string.
                 Defaults to FALLBACK_PROVIDER environment variable.
+            provider_configs: Optional per-provider kwargs keyed by provider scheme,
+                merged into the S3Provider constructor for the matching provider.
+                Example: {"mega": {"transfer_config": TransferConfig(...)}}
 
         Raises:
             ValueError: If fallback_provider not found in providers
@@ -39,13 +47,16 @@ class Storage:
                     endpoint=creds.endpoint,
                     access_key_id=creds.access_key,
                     secret_access_key=creds.secret_key,
+                    **(provider_configs or {}).get(creds.provider_scheme, {}),
                 )
 
-        self.fallback_provider: str = fallback_provider
+        scheme, _, bucket = fallback_provider.partition("://")
+        self.fallback_provider: str = scheme
+        self.fallback_bucket: str | None = bucket or None
 
-        if fallback_provider not in self.providers:
+        if self.fallback_provider not in self.providers:
             raise ValueError(
-                f"Fallback provider '{fallback_provider}' not found in providers"
+                f"Fallback provider '{self.fallback_provider}' not found in providers"
             )
 
     def upload_file(self, remote_file_uri: str, local_file_path: str) -> str:
@@ -76,11 +87,11 @@ class Storage:
             if self.fallback_provider != parsed_uri.scheme:
                 try:
                     fallback: S3Provider = self.providers[self.fallback_provider]
-                    # Use same bucket and key with fallback provider
+                    # Use configured fallback bucket if set, else the same bucket
                     return fallback.upload_file(
                         file_name=parsed_uri.path.lstrip("/"),
                         file_path=local_file_path,
-                        bucket=parsed_uri.netloc,
+                        bucket=self.fallback_bucket or parsed_uri.netloc,
                     )
                 except Exception as fallback_error:
                     raise Exception(

{fallbacks3-0.3.1 → fallbacks3-0.5.0}/fallbacks3.egg-info/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: fallbacks3
-Version: 0.3.1
+Version: 0.5.0
 Summary: S3-compatible storage library with automatic fallback support
 Author-email: Mila de Oliveira <mila.oliveira@palver.com.br>
 Project-URL: Homepage, https://github.com/palverdata/fallbacks3
 Project-URL: Repository, https://github.com/palverdata/fallbacks3
 Project-URL: Issues, https://github.com/palverdata/fallbacks3/issues
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Requires-Dist: boto3>=1.26.0
 Requires-Dist: pydantic-settings>=2.0.0
@@ -49,6 +49,15 @@ PROVIDERS="ps3://access_key:secret_key@ps3.palver.com,r2://access_key:secret_key
 FALLBACK_PROVIDER="r2"
 ```
 
+`FALLBACK_PROVIDER` may also be set as a `<scheme>://<bucket>` URI to redirect fallback
+uploads to a specific bucket instead of reusing the original request's bucket. The scheme
+must still be one of the providers in `PROVIDERS`.
+
+```bash
+# On fallback, upload to bucket "bucket-v2" on the r2 provider
+FALLBACK_PROVIDER="r2://bucket-v2"
+```
+
 
 ### Provider URI Format
 
@@ -108,7 +117,7 @@ print(signed_url)  # "https://ps3.palver.com/palver-whatsapp/audio.mp3?signature
 
 ### Upload with Automatic Fallback
 
-If the primary provider fails for the upload method, the library automatically retries with the fallback provider (using the same bucket and file path), as to ensure files are not lost.
+If the primary provider fails for the upload method, the library automatically retries with the fallback provider (using the same bucket and file path, unless `FALLBACK_PROVIDER` specifies a bucket), as to ensure files are not lost.
 
 ```python
 # If ps3 fails, automatically falls back to r2

{fallbacks3-0.3.1 → fallbacks3-0.5.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fallbacks3"
-version = "0.3.1"
+version = "0.5.0"
 description = "S3-compatible storage library with automatic fallback support"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 authors = [
     {name = "Mila de Oliveira", email = "mila.oliveira@palver.com.br"}
 ]