fallbacks3 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fallbacks3
-Version: 0.4.0
+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
@@ -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.4.0 → 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.4.0 → fallbacks3-0.5.0}/fallbacks3/storage.py

@@ -22,8 +22,11 @@ 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.
@@ -47,11 +50,13 @@ class Storage:
                     **(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:
@@ -82,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.4.0 → fallbacks3-0.5.0}/fallbacks3.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fallbacks3
-Version: 0.4.0
+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
@@ -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.4.0 → fallbacks3-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "fallbacks3"
-version = "0.4.0"
+version = "0.5.0"
 description = "S3-compatible storage library with automatic fallback support"
 readme = "README.md"
 requires-python = ">=3.10"