fal 1.19.2__tar.gz → 1.20.1__tar.gz

{fal-1.19.2/fal.egg-info → fal-1.20.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fal
-Version: 1.19.2
+Version: 1.20.1
 Summary: fal is an easy-to-use Serverless Python Framework
 Author: Features & Labels <support@fal.ai>
 Requires-Python: >=3.8

{fal-1.19.2 → fal-1.20.1/fal.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fal
-Version: 1.19.2
+Version: 1.20.1
 Summary: fal is an easy-to-use Serverless Python Framework
 Author: Features & Labels <support@fal.ai>
 Requires-Python: >=3.8

{fal-1.19.2 → fal-1.20.1}/fal.egg-info/SOURCES.txt

@@ -176,5 +176,6 @@ tests/mainify_package/utils.py
 tests/toolkit/file_test.py
 tests/toolkit/image_test.py
 tests/toolkit/test_types.py
+tests/toolkit/file/providers/test_fal_retry.py
 tests/toolkit/utils/retry.py
 tools/demo_script.py

{fal-1.19.2 → fal-1.20.1}/src/fal/_fal_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.19.2'
-__version_tuple__ = version_tuple = (1, 19, 2)
+__version__ = version = '1.20.1'
+__version_tuple__ = version_tuple = (1, 20, 1)

{fal-1.19.2 → fal-1.20.1}/src/fal/api.py

@@ -1183,6 +1183,9 @@ class BaseServable:
         app_info.labels(version=self.version).set(1)
 
         app = self._build_app()
+
+        # We use the default workers=1 config because setup function can be heavy
+        # and it runs once per worker.
         server = Server(
             config=Config(app, host="0.0.0.0", port=8080, timeout_keep_alive=300)
         )

{fal-1.19.2 → fal-1.20.1}/src/fal/cli/files.py

@@ -48,11 +48,19 @@ def add_parser(main_subparsers, parents):
     subparsers = parser.add_subparsers(
         title="Commands",
         metavar="command",
+        dest="cmd",
         required=True,
         parser_class=FalClientParser,
     )
 
-    list_parser = subparsers.add_parser("list", aliases=["ls"], parents=parents)
+    list_help = "List files."
+    list_parser = subparsers.add_parser(
+        "list",
+        aliases=["ls"],
+        description=list_help,
+        help=list_help,
+        parents=parents,
+    )
     list_parser.add_argument(
         "path",
         nargs="?",
@@ -62,7 +70,13 @@ def add_parser(main_subparsers, parents):
     )
     list_parser.set_defaults(func=_list)
 
-    download_parser = subparsers.add_parser("download", parents=parents)
+    download_help = "Download files."
+    download_parser = subparsers.add_parser(
+        "download",
+        description=download_help,
+        help=download_help,
+        parents=parents,
+    )
     download_parser.add_argument(
         "remote_path", type=str, help="Remote path to download"
     )
@@ -71,12 +85,24 @@ def add_parser(main_subparsers, parents):
     )
     download_parser.set_defaults(func=_download)
 
-    upload_parser = subparsers.add_parser("upload", parents=parents)
+    upload_help = "Upload files."
+    upload_parser = subparsers.add_parser(
+        "upload",
+        description=upload_help,
+        help=upload_help,
+        parents=parents,
+    )
     upload_parser.add_argument("local_path", type=str, help="Local path to upload")
     upload_parser.add_argument("remote_path", type=str, help="Remote path to upload to")
     upload_parser.set_defaults(func=_upload)
 
-    upload_url_parser = subparsers.add_parser("upload-url", parents=parents)
+    upload_url_help = "Upload file from URL."
+    upload_url_parser = subparsers.add_parser(
+        "upload-url",
+        description=upload_url_help,
+        help=upload_url_help,
+        parents=parents,
+    )
     upload_url_parser.add_argument("url", type=str, help="URL to upload")
     upload_url_parser.add_argument(
         "remote_path", type=str, help="Remote path to upload to"

{fal-1.19.2 → fal-1.20.1}/src/fal/toolkit/file/providers/fal.py

@@ -9,7 +9,7 @@ from contextlib import contextmanager
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Generator, Generic, TypeVar
+from typing import Any, Generator, Generic, TypeVar
 from urllib.error import HTTPError
 from urllib.parse import urlparse, urlunparse
 from urllib.request import Request, urlopen
@@ -26,15 +26,46 @@ _FAL_CDN_V3 = "https://v3.fal.media"
 DEFAULT_REQUEST_TIMEOUT = 10
 PUT_REQUEST_TIMEOUT = 5 * 60
 
+MAX_ATTEMPTS = 5
+BASE_DELAY = 0.1
+MAX_DELAY = 30
+RETRY_CODES = [408, 409, 429, 500, 502, 503, 504]
+
 
 @contextmanager
 def _urlopen(
-    request: Request, timeout: int = DEFAULT_REQUEST_TIMEOUT
+    request: Request,
+    timeout: int = DEFAULT_REQUEST_TIMEOUT,
 ) -> Generator[addinfourl, None, None]:
     with urlopen(request, timeout=timeout) as response:
         yield response
 
 
+def _should_retry(exc: Exception) -> bool:
+    if isinstance(exc, HTTPError) and exc.code in RETRY_CODES:
+        return True
+
+    return False
+
+
+@contextmanager
+def _maybe_retry_request(
+    request: Request,
+    **kwargs: Any,
+) -> Generator[addinfourl, None, None]:
+    _urlopen_with_retry = retry(
+        max_retries=MAX_ATTEMPTS,
+        base_delay=BASE_DELAY,
+        max_delay=MAX_DELAY,
+        backoff_type="exponential",
+        jitter=True,
+        should_retry=_should_retry,
+    )(_urlopen)
+
+    with _urlopen_with_retry(request, **kwargs) as response:
+        yield response
+
+
 @dataclass
 class FalV2Token:
     token: str
@@ -92,7 +123,7 @@ class FalV2TokenManager:
             data=b"{}",
             method="POST",
         )
-        with _urlopen(req) as response:
+        with _maybe_retry_request(req) as response:
             result = json.load(response)
 
         parsed_base_url = urlparse(result["base_url"])
@@ -137,7 +168,6 @@ LIFECYCLE_PREFERENCE: VariableReference[dict[str, str] | None] = VariableReferen
 
 @dataclass
 class FalFileRepositoryBase(FileRepository):
-    @retry(max_retries=3, base_delay=1, backoff_type="exponential", jitter=True)
     def _save(
         self, file: FileData, storage_type: str, headers: dict[str, str] | None = None
     ) -> str:
@@ -171,7 +201,7 @@ class FalFileRepositoryBase(FileRepository):
                 headers=headers,
                 method="POST",
             )
-            with _urlopen(req) as response:
+            with _maybe_retry_request(req) as response:
                 result = json.load(response)
 
             upload_url = result["upload_url"]
@@ -188,7 +218,7 @@ class FalFileRepositoryBase(FileRepository):
                 headers={"Content-Type": file.content_type},
             )
 
-            with _urlopen(req, timeout=PUT_REQUEST_TIMEOUT):
+            with _maybe_retry_request(req, timeout=PUT_REQUEST_TIMEOUT):
                 pass
 
             return result["file_url"]
@@ -265,7 +295,7 @@ class MultipartUploadGCS:
                 ).encode(),
             )
 
-            with _urlopen(req) as response:
+            with _maybe_retry_request(req) as response:
                 result = json.load(response)
                 self._access_url = result["file_url"]
                 self._upload_url = result["upload_url"]
@@ -275,7 +305,6 @@ class MultipartUploadGCS:
                 f"Error initiating upload. Status {exc.status}: {exc.reason}"
             )
 
-    @retry(max_retries=5, base_delay=1, backoff_type="exponential", jitter=True)
     def upload_part(self, part_number: int, data: bytes) -> None:
         initiate_upload_url = self.upload_url + f"/{part_number}"
         req = Request(
@@ -285,7 +314,7 @@ class MultipartUploadGCS:
         )
 
         try:
-            with _urlopen(req) as response:
+            with _maybe_retry_request(req) as response:
                 result = json.load(response)
                 upload_url = result["upload_url"]
         except HTTPError as exc:
@@ -301,7 +330,7 @@ class MultipartUploadGCS:
         )
 
         try:
-            with _urlopen(req, timeout=PUT_REQUEST_TIMEOUT) as resp:
+            with _maybe_retry_request(req, timeout=PUT_REQUEST_TIMEOUT) as resp:
                 self._parts.append(
                     {
                         "part_number": part_number,
@@ -331,7 +360,7 @@ class MultipartUploadGCS:
                     }
                 ).encode(),
             )
-            with _urlopen(req):
+            with _maybe_retry_request(req):
                 pass
         except HTTPError as e:
             raise FileUploadException(
@@ -427,7 +456,6 @@ class FalFileRepository(FalFileRepositoryBase):
         if object_lifecycle_preference:
             headers["X-Fal-Object-Lifecycle"] = json.dumps(object_lifecycle_preference)
 
-    @retry(max_retries=3, base_delay=1, backoff_type="exponential", jitter=True)
     def save(
         self,
         file: FileData,
@@ -536,7 +564,7 @@ class MultipartUpload:
                     }
                 ).encode(),
             )
-            with _urlopen(req) as response:
+            with _maybe_retry_request(req) as response:
                 result = json.load(response)
                 self._upload_url = result["upload_url"]
                 self._file_url = result["file_url"]
@@ -556,7 +584,7 @@ class MultipartUpload:
         )
 
         try:
-            with _urlopen(req, timeout=PUT_REQUEST_TIMEOUT) as resp:
+            with _maybe_retry_request(req, timeout=PUT_REQUEST_TIMEOUT) as resp:
                 self._parts.append(
                     {
                         "part_number": part_number,
@@ -581,7 +609,7 @@ class MultipartUpload:
                 },
                 data=json.dumps({"parts": self._parts}).encode(),
             )
-            with _urlopen(req):
+            with _maybe_retry_request(req):
                 pass
         except HTTPError as e:
             raise FileUploadException(
@@ -734,7 +762,7 @@ class MultipartUploadV3:
                 ).encode(),
             )
 
-            with _urlopen(req) as response:
+            with _maybe_retry_request(req) as response:
                 result = json.load(response)
                 self._access_url = result["file_url"]
                 self._upload_url = result["upload_url"]
@@ -744,7 +772,6 @@ class MultipartUploadV3:
                 f"Error initiating upload. Status {exc.status}: {exc.reason}"
             )
 
-    @retry(max_retries=5, base_delay=1, backoff_type="exponential", jitter=True)
     def upload_part(self, part_number: int, data: bytes) -> None:
         parsed = urlparse(self.upload_url)
         part_path = parsed.path + f"/{part_number}"
@@ -760,7 +787,7 @@ class MultipartUploadV3:
         )
 
         try:
-            with _urlopen(req, timeout=PUT_REQUEST_TIMEOUT) as resp:
+            with _maybe_retry_request(req, timeout=PUT_REQUEST_TIMEOUT) as resp:
                 self._parts.append(
                     {
                         "partNumber": part_number,
@@ -788,7 +815,7 @@ class MultipartUploadV3:
                 },
                 data=json.dumps({"parts": self._parts}).encode(),
             )
-            with _urlopen(req):
+            with _maybe_retry_request(req):
                 pass
         except HTTPError as e:
             raise FileUploadException(
@@ -928,7 +955,7 @@ class InternalMultipartUploadV3:
                     "X-Fal-File-Name": self.file_name,
                 },
             )
-            with _urlopen(req) as response:
+            with _maybe_retry_request(req) as response:
                 result = json.load(response)
                 self._access_url = result["access_url"]
                 self._upload_id = result["uploadId"]
@@ -938,7 +965,6 @@ class InternalMultipartUploadV3:
                 f"Error initiating upload. Status {exc.status}: {exc.reason}"
             )
 
-    @retry(max_retries=5, base_delay=1, backoff_type="exponential", jitter=True)
     def upload_part(self, part_number: int, data: bytes) -> None:
         url = f"{self.access_url}/multipart/{self.upload_id}/{part_number}"
 
@@ -953,7 +979,7 @@ class InternalMultipartUploadV3:
         )
 
         try:
-            with _urlopen(req, timeout=PUT_REQUEST_TIMEOUT) as resp:
+            with _maybe_retry_request(req, timeout=PUT_REQUEST_TIMEOUT) as resp:
                 self._parts.append(
                     {
                         "partNumber": part_number,
@@ -979,7 +1005,7 @@ class InternalMultipartUploadV3:
                 },
                 data=json.dumps({"parts": self._parts}).encode(),
             )
-            with _urlopen(req):
+            with _maybe_retry_request(req):
                 pass
         except HTTPError as e:
             raise FileUploadException(
@@ -1067,7 +1093,6 @@ class InternalMultipartUploadV3:
 
 @dataclass
 class FalFileRepositoryV2(FalFileRepositoryBase):
-    @retry(max_retries=3, base_delay=1, backoff_type="exponential", jitter=True)
     def save(
         self,
         file: FileData,
@@ -1105,7 +1130,7 @@ class FalFileRepositoryV2(FalFileRepositoryBase):
                 headers=headers,
                 method="PUT",
             )
-            with _urlopen(req, timeout=PUT_REQUEST_TIMEOUT) as response:
+            with _maybe_retry_request(req, timeout=PUT_REQUEST_TIMEOUT) as response:
                 result = json.load(response)
 
             return result["file_url"]
@@ -1177,7 +1202,6 @@ class FalCDNFileRepository(FileRepository):
                 object_lifecycle_preference
             )
 
-    @retry(max_retries=3, base_delay=1, backoff_type="exponential", jitter=True)
     def save(
         self,
         file: FileData,
@@ -1199,7 +1223,7 @@ class FalCDNFileRepository(FileRepository):
         url = os.getenv("FAL_CDN_HOST", _FAL_CDN) + "/files/upload"
         request = Request(url, headers=headers, method="POST", data=file.data)
         try:
-            with _urlopen(request) as response:
+            with _maybe_retry_request(request) as response:
                 result = json.load(response)
         except HTTPError as e:
             raise FileUploadException(
@@ -1236,7 +1260,6 @@ class FalFileRepositoryV3(FileRepository):
             "User-Agent": "fal/0.1.0",
         }
 
-    @retry(max_retries=3, base_delay=1, backoff_type="exponential", jitter=True)
     def save(
         self,
         file: FileData,
@@ -1279,7 +1302,7 @@ class FalFileRepositoryV3(FileRepository):
             ).encode(),
         )
         try:
-            with _urlopen(request) as response:
+            with _maybe_retry_request(request) as response:
                 result = json.load(response)
                 file_url = result["file_url"]
                 upload_url = result["upload_url"]
@@ -1295,7 +1318,7 @@ class FalFileRepositoryV3(FileRepository):
             data=file.data,
         )
         try:
-            with _urlopen(request, timeout=PUT_REQUEST_TIMEOUT):
+            with _maybe_retry_request(request, timeout=PUT_REQUEST_TIMEOUT):
                 pass
         except HTTPError as e:
             raise FileUploadException(
@@ -1358,7 +1381,6 @@ class InternalFalFileRepositoryV3(FileRepository):
         if object_lifecycle_preference:
             headers["X-Fal-Object-Lifecycle"] = json.dumps(object_lifecycle_preference)
 
-    @retry(max_retries=3, base_delay=1, backoff_type="exponential", jitter=True)
     def save(
         self,
         file: FileData,
@@ -1393,7 +1415,7 @@ class InternalFalFileRepositoryV3(FileRepository):
         url = os.getenv("FAL_CDN_V3_HOST", _FAL_CDN_V3) + "/files/upload"
         request = Request(url, headers=headers, method="POST", data=file.data)
         try:
-            with _urlopen(request) as response:
+            with _maybe_retry_request(request) as response:
                 result = json.load(response)
         except HTTPError as e:
             raise FileUploadException(

{fal-1.19.2 → fal-1.20.1}/src/fal/toolkit/utils/retry.py

@@ -2,7 +2,7 @@ import functools
 import random
 import time
 import traceback
-from typing import Any, Callable, Literal
+from typing import Any, Callable, Literal, Optional
 
 BackoffType = Literal["exponential", "fixed"]
 
@@ -13,6 +13,7 @@ def retry(
     max_delay: float = 60.0,
     backoff_type: BackoffType = "exponential",
     jitter: bool = False,
+    should_retry: Optional[Callable[[Exception], bool]] = None,
 ) -> Callable:
     def decorator(func: Callable) -> Callable:
         @functools.wraps(func)
@@ -22,6 +23,9 @@ def retry(
                 try:
                     return func(*args, **kwargs)
                 except Exception as e:
+                    if should_retry is not None and not should_retry(e):
+                        raise
+
                     retries += 1
                     print(f"Retrying {retries} of {max_retries}...")
                     if retries == max_retries:

{fal-1.19.2 → fal-1.20.1}/tests/test_apps.py

@@ -5,7 +5,7 @@ import subprocess
 import time
 import uuid
 from contextlib import contextmanager, suppress
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from typing import Generator, List, Tuple
 
 import httpx
@@ -626,7 +626,9 @@ def test_app_client_async(test_sleep_app: str):
 # If the logging subsystem is not working for some nodes, this test will flake
 @pytest.mark.flaky(max_runs=10)
 def test_traceback_logs(test_exception_app: AppClient):
-    date = (datetime.utcnow() - timedelta(seconds=1)).isoformat()
+    date = (
+        datetime.now(timezone.utc).replace(tzinfo=None) - timedelta(seconds=1)
+    ).isoformat()
 
     with pytest.raises(AppClientError):
         test_exception_app.fail({})

fal-1.20.1/tests/toolkit/file/providers/test_fal_retry.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from unittest import mock
+from urllib.error import HTTPError
+from urllib.request import Request
+
+import pytest
+
+from fal.toolkit.file.providers.fal import _maybe_retry_request
+
+RETRY_CODES = [408, 409, 429, 500, 502, 503, 504]
+NON_RETRY_CODES = [400, 401, 403, 404, 422]
+
+
+class MockResponse:
+    """Mock response object that mimics urllib.response.addinfourl"""
+
+    def __init__(self, data: str = '{"result": "success"}', status: int = 200):
+        self.data = data.encode()
+        self.status = status
+        self.headers = {"Content-Type": "application/json"}
+
+    def read(self):
+        return self.data
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        pass
+
+
+def test_successful_request_no_retry():
+    request = Request("https://example.com/test")
+
+    with mock.patch("fal.toolkit.file.providers.fal._urlopen") as mock_urlopen:
+        mock_response = MockResponse()
+        mock_context = mock.MagicMock()
+        mock_context.__enter__.return_value = mock_response
+        mock_context.__exit__.return_value = None
+        mock_urlopen.return_value = mock_context
+
+        with _maybe_retry_request(request) as response:
+            assert response == mock_response
+
+        assert mock_urlopen.call_count == 1
+
+
+@pytest.mark.parametrize("error_code", RETRY_CODES)
+def test_retry_on_retryable_http_codes(error_code):
+    request = Request("https://example.com/test")
+
+    call_count = 0
+
+    def mock_urlopen_side_effect(*args, **kwargs):
+        nonlocal call_count
+        call_count += 1
+
+        if call_count == 1:
+            raise HTTPError(
+                url="https://example.com/test",
+                code=error_code,
+                msg=f"HTTP {error_code} Error",
+                hdrs={},
+                fp=None,
+            )
+        else:
+            mock_response = MockResponse()
+            mock_context = mock.MagicMock()
+            mock_context.__enter__.return_value = mock_response
+            mock_context.__exit__.return_value = None
+            return mock_context
+
+    with mock.patch(
+        "fal.toolkit.file.providers.fal._urlopen", side_effect=mock_urlopen_side_effect
+    ):
+        with mock.patch(
+            "fal.toolkit.utils.retry.time.sleep"
+        ):  # Mock sleep to speed up tests
+            with _maybe_retry_request(request) as response:
+                assert response is not None
+
+    assert call_count == 2
+
+
+@pytest.mark.parametrize("error_code", NON_RETRY_CODES)
+def test_no_retry_on_non_retryable_http_codes(error_code):
+    request = Request("https://example.com/test")
+
+    call_count = 0
+
+    def mock_urlopen_side_effect(*args, **kwargs):
+        nonlocal call_count
+        call_count += 1
+        raise HTTPError(
+            url="https://example.com/test",
+            code=error_code,
+            msg=f"HTTP {error_code} Error",
+            hdrs={},
+            fp=None,
+        )
+
+    with mock.patch(
+        "fal.toolkit.file.providers.fal._urlopen", side_effect=mock_urlopen_side_effect
+    ):
+        with pytest.raises(HTTPError) as exc_info:
+            with _maybe_retry_request(request):
+                pass
+
+        assert exc_info.value.code == error_code
+        assert call_count == 1
+
+
+def test_non_http_exception_not_retried():
+    """Test that non-HTTP exceptions are not retried"""
+    request = Request("https://example.com/test")
+
+    call_count = 0
+
+    def mock_urlopen_side_effect(*args, **kwargs):
+        nonlocal call_count
+        call_count += 1
+        raise ValueError("Network error")
+
+    with mock.patch(
+        "fal.toolkit.file.providers.fal._urlopen", side_effect=mock_urlopen_side_effect
+    ):
+        with pytest.raises(ValueError) as exc_info:
+            with _maybe_retry_request(request):
+                pass
+
+        assert str(exc_info.value) == "Network error"
+        assert call_count == 1
+
+
+def test_max_retries_exhausted_for_retryable_errors():
+    """Test that retries are exhausted after MAX_ATTEMPTS for retryable HTTP errors"""
+    request = Request("https://example.com/test")
+
+    call_count = 0
+
+    def mock_urlopen_side_effect(*args, **kwargs):
+        nonlocal call_count
+        call_count += 1
+        # Always fail with a retryable error
+        raise HTTPError(
+            url="https://example.com/test",
+            code=500,
+            msg="Internal Server Error",
+            hdrs={},
+            fp=None,
+        )
+
+    with mock.patch(
+        "fal.toolkit.file.providers.fal._urlopen", side_effect=mock_urlopen_side_effect
+    ):
+        with mock.patch(
+            "fal.toolkit.utils.retry.time.sleep"
+        ):  # Mock sleep to speed up tests
+            with pytest.raises(HTTPError) as exc_info:
+                with _maybe_retry_request(request):
+                    pass
+
+        assert exc_info.value.code == 500
+        assert call_count == 5