fal 1.3.3__py3-none-any.whl → 1.7.2__py3-none-any.whl

fal/toolkit/file/file.py

@@ -8,6 +8,7 @@ from urllib.parse import urlparse
 from zipfile import ZipFile
 
 import pydantic
+from fastapi import Request
 
 # https://github.com/pydantic/pydantic/pull/2573
 if not hasattr(pydantic, "__version__") or pydantic.__version__.startswith("1."):
@@ -21,9 +22,11 @@ else:
 from pydantic import BaseModel, Field
 
 from fal.toolkit.file.providers.fal import (
+    LIFECYCLE_PREFERENCE,
     FalCDNFileRepository,
     FalFileRepository,
     FalFileRepositoryV2,
+    FalFileRepositoryV3,
     InMemoryRepository,
 )
 from fal.toolkit.file.providers.gcp import GoogleStorageRepository
@@ -36,6 +39,7 @@ FileRepositoryFactory = Callable[[], FileRepository]
 BUILT_IN_REPOSITORIES: dict[RepositoryId, FileRepositoryFactory] = {
     "fal": lambda: FalFileRepository(),
     "fal_v2": lambda: FalFileRepositoryV2(),
+    "fal_v3": lambda: FalFileRepositoryV3(),
     "in_memory": lambda: InMemoryRepository(),
     "gcp_storage": lambda: GoogleStorageRepository(),
     "r2": lambda: R2Repository(),
@@ -43,7 +47,10 @@ BUILT_IN_REPOSITORIES: dict[RepositoryId, FileRepositoryFactory] = {
 }
 
 
-def get_builtin_repository(id: RepositoryId) -> FileRepository:
+def get_builtin_repository(id: RepositoryId | FileRepository) -> FileRepository:
+    if isinstance(id, FileRepository):
+        return id
+
     if id not in BUILT_IN_REPOSITORIES.keys():
         raise ValueError(f'"{id}" is not a valid built-in file repository')
     return BUILT_IN_REPOSITORIES[id]()
@@ -51,7 +58,9 @@ def get_builtin_repository(id: RepositoryId) -> FileRepository:
 
 get_builtin_repository.__module__ = "__main__"
 
-DEFAULT_REPOSITORY: FileRepository | RepositoryId = "fal"
+DEFAULT_REPOSITORY: FileRepository | RepositoryId = "fal_v3"
+FALLBACK_REPOSITORY: FileRepository | RepositoryId = "cdn"
+OBJECT_LIFECYCLE_PREFERENCE_KEY = "x-fal-object-lifecycle-preference"
 
 
 class File(BaseModel):
@@ -116,7 +125,8 @@ class File(BaseModel):
             url=url,
             content_type=None,
             file_name=None,
-            repository=DEFAULT_REPOSITORY,
+            file_size=None,
+            file_data=None,
         )
 
     @classmethod
@@ -126,17 +136,38 @@ class File(BaseModel):
         content_type: Optional[str] = None,
         file_name: Optional[str] = None,
         repository: FileRepository | RepositoryId = DEFAULT_REPOSITORY,
+        fallback_repository: Optional[
+            FileRepository | RepositoryId
+        ] = FALLBACK_REPOSITORY,
+        request: Optional[Request] = None,
+        save_kwargs: Optional[dict] = None,
+        fallback_save_kwargs: Optional[dict] = None,
     ) -> File:
-        repo = (
-            repository
-            if isinstance(repository, FileRepository)
-            else get_builtin_repository(repository)
-        )
+        repo = get_builtin_repository(repository)
+
+        save_kwargs = save_kwargs or {}
+        fallback_save_kwargs = fallback_save_kwargs or {}
 
         fdata = FileData(data, content_type, file_name)
 
+        object_lifecycle_preference = (
+            request_lifecycle_preference(request) or LIFECYCLE_PREFERENCE.get()
+        )
+
+        try:
+            url = repo.save(fdata, object_lifecycle_preference, **save_kwargs)
+        except Exception:
+            if not fallback_repository:
+                raise
+
+            fallback_repo = get_builtin_repository(fallback_repository)
+
+            url = fallback_repo.save(
+                fdata, object_lifecycle_preference, **fallback_save_kwargs
+            )
+
         return cls(
-            url=repo.save(fdata),
+            url=url,
             content_type=fdata.content_type,
             file_name=fdata.file_name,
             file_size=len(data),
@@ -150,24 +181,49 @@ class File(BaseModel):
         content_type: Optional[str] = None,
         repository: FileRepository | RepositoryId = DEFAULT_REPOSITORY,
         multipart: bool | None = None,
+        fallback_repository: Optional[
+            FileRepository | RepositoryId
+        ] = FALLBACK_REPOSITORY,
+        request: Optional[Request] = None,
+        save_kwargs: Optional[dict] = None,
+        fallback_save_kwargs: Optional[dict] = None,
     ) -> File:
         file_path = Path(path)
         if not file_path.exists():
             raise FileNotFoundError(f"File {file_path} does not exist")
 
-        repo = (
-            repository
-            if isinstance(repository, FileRepository)
-            else get_builtin_repository(repository)
-        )
+        repo = get_builtin_repository(repository)
 
-        content_type = content_type or "application/octet-stream"
+        save_kwargs = save_kwargs or {}
+        fallback_save_kwargs = fallback_save_kwargs or {}
 
-        url, data = repo.save_file(
-            file_path,
-            content_type=content_type,
-            multipart=multipart,
+        content_type = content_type or "application/octet-stream"
+        object_lifecycle_preference = (
+            request_lifecycle_preference(request) or LIFECYCLE_PREFERENCE.get()
         )
+
+        try:
+            url, data = repo.save_file(
+                file_path,
+                content_type=content_type,
+                multipart=multipart,
+                object_lifecycle_preference=object_lifecycle_preference,
+                **save_kwargs,
+            )
+        except Exception:
+            if not fallback_repository:
+                raise
+
+            fallback_repo = get_builtin_repository(fallback_repository)
+
+            url, data = fallback_repo.save_file(
+                file_path,
+                content_type=content_type,
+                multipart=multipart,
+                object_lifecycle_preference=object_lifecycle_preference,
+                **fallback_save_kwargs,
+            )
+
         return cls(
             url=url,
             file_data=data.data if data else None,
@@ -223,3 +279,20 @@ class CompressedFile(File):
     def __del__(self):
         if self.extract_dir:
             shutil.rmtree(self.extract_dir)
+
+
+def request_lifecycle_preference(request: Optional[Request]) -> dict[str, str] | None:
+    import json
+
+    if request is None:
+        return None
+
+    preference_str = request.headers.get(OBJECT_LIFECYCLE_PREFERENCE_KEY)
+    if preference_str is None:
+        return None
+
+    try:
+        return json.loads(preference_str)
+    except Exception as e:
+        print(f"Failed to parse object lifecycle preference: {e}")
+        return None