fal 1.5.2__tar.gz → 1.5.4__tar.gz

{fal-1.5.2 → fal-1.5.4}/.gitignore

@@ -1 +1,2 @@
 /src/fal/_fal_version.py
+/docs/*

fal-1.5.4/Makefile

@@ -0,0 +1,24 @@
+MAKEFILE_DIR := $(patsubst %/,%,$(dir $(abspath $(lastword $(MAKEFILE_LIST)))))
+
+SPHINXOPTS    = --fresh-env
+SPHINXBUILD   = sphinx-build
+SPHINXAPIDOC  = sphinx-apidoc
+SOURCEDIR     = $(MAKEFILE_DIR)/docs
+BUILDDIR      = $(MAKEFILE_DIR)/docs/_build
+PROJECTDIR    = $(MAKEFILE_DIR)/src/fal
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile clean apidoc html docs
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+apidoc:
+	$(SPHINXAPIDOC) -f -o "$(SOURCEDIR)" "$(PROJECTDIR)"
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+docs: apidoc html

{fal-1.5.2 → fal-1.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fal
-Version: 1.5.2
+Version: 1.5.4
 Summary: fal is an easy-to-use Serverless Python Framework
 Author: Features & Labels <support@fal.ai>
 Requires-Python: >=3.8
@@ -23,6 +23,7 @@ Requires-Dist: rich_argparse
 Requires-Dist: packaging>=21.3
 Requires-Dist: pathspec<1,>=0.11.1
 Requires-Dist: pydantic!=2.0.*,!=2.1.*,!=2.2.*,!=2.3.*,!=2.4.*,<3
+Requires-Dist: structlog>=22.0
 Requires-Dist: fastapi<1,>=0.99.1
 Requires-Dist: starlette-exporter>=0.21.0
 Requires-Dist: httpx>=0.15.4
@@ -37,6 +38,10 @@ Requires-Dist: pyjwt[crypto]<3,>=2.8.0
 Requires-Dist: uvicorn<1,>=0.29.0
 Requires-Dist: cookiecutter
 Requires-Dist: tomli
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
 Provides-Extra: test
 Requires-Dist: pytest<8; extra == "test"
 Requires-Dist: pytest-asyncio; extra == "test"
@@ -44,7 +49,7 @@ Requires-Dist: pytest-xdist; extra == "test"
 Requires-Dist: flaky; extra == "test"
 Requires-Dist: boto3; extra == "test"
 Provides-Extra: dev
-Requires-Dist: fal[test]; extra == "dev"
+Requires-Dist: fal[docs,test]; extra == "dev"
 Requires-Dist: openapi-python-client<1,>=0.14.1; extra == "dev"
 
 [![PyPI](https://img.shields.io/pypi/v/fal.svg?logo=PyPI)](https://pypi.org/project/fal)

fal-1.5.4/docs/conf.py

@@ -0,0 +1,31 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'fal_sdk'
+copyright = '2024, FAL Team'
+author = 'FAL Team'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx_autodoc_typehints'
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']

fal-1.5.4/docs/index.rst

@@ -0,0 +1,18 @@
+.. fal_sdk documentation master file, created by
+   sphinx-quickstart on Wed Oct  2 05:09:49 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+fal_sdk documentation
+=====================
+
+Add your content using ``reStructuredText`` syntax. See the
+`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
+documentation for details.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   modules

{fal-1.5.2 → fal-1.5.4}/fal.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: fal
-Version: 1.5.2
+Version: 1.5.4
 Summary: fal is an easy-to-use Serverless Python Framework
 Author: Features & Labels <support@fal.ai>
 Requires-Python: >=3.8
@@ -23,6 +23,7 @@ Requires-Dist: rich_argparse
 Requires-Dist: packaging>=21.3
 Requires-Dist: pathspec<1,>=0.11.1
 Requires-Dist: pydantic!=2.0.*,!=2.1.*,!=2.2.*,!=2.3.*,!=2.4.*,<3
+Requires-Dist: structlog>=22.0
 Requires-Dist: fastapi<1,>=0.99.1
 Requires-Dist: starlette-exporter>=0.21.0
 Requires-Dist: httpx>=0.15.4
@@ -37,6 +38,10 @@ Requires-Dist: pyjwt[crypto]<3,>=2.8.0
 Requires-Dist: uvicorn<1,>=0.29.0
 Requires-Dist: cookiecutter
 Requires-Dist: tomli
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
 Provides-Extra: test
 Requires-Dist: pytest<8; extra == "test"
 Requires-Dist: pytest-asyncio; extra == "test"
@@ -44,7 +49,7 @@ Requires-Dist: pytest-xdist; extra == "test"
 Requires-Dist: flaky; extra == "test"
 Requires-Dist: boto3; extra == "test"
 Provides-Extra: dev
-Requires-Dist: fal[test]; extra == "dev"
+Requires-Dist: fal[docs,test]; extra == "dev"
 Requires-Dist: openapi-python-client<1,>=0.14.1; extra == "dev"
 
 [![PyPI](https://img.shields.io/pypi/v/fal.svg?logo=PyPI)](https://pypi.org/project/fal)

{fal-1.5.2 → fal-1.5.4}/fal.egg-info/SOURCES.txt

@@ -1,7 +1,10 @@
 .gitignore
+Makefile
 README.md
 openapi_rest.config.yaml
 pyproject.toml
+docs/conf.py
+docs/index.rst
 fal.egg-info/PKG-INFO
 fal.egg-info/SOURCES.txt
 fal.egg-info/dependency_links.txt

{fal-1.5.2 → fal-1.5.4}/fal.egg-info/requires.txt

@@ -16,6 +16,7 @@ rich_argparse
 packaging>=21.3
 pathspec<1,>=0.11.1
 pydantic!=2.0.*,!=2.1.*,!=2.2.*,!=2.3.*,!=2.4.*,<3
+structlog>=22.0
 fastapi<1,>=0.99.1
 starlette-exporter>=0.21.0
 httpx>=0.15.4
@@ -34,9 +35,14 @@ tomli
 importlib-metadata>=4.4
 
 [dev]
-fal[test]
+fal[docs,test]
 openapi-python-client<1,>=0.14.1
 
+[docs]
+sphinx
+sphinx-rtd-theme
+sphinx-autodoc-typehints
+
 [test]
 pytest<8
 pytest-asyncio

{fal-1.5.2 → fal-1.5.4}/pyproject.toml

@@ -41,6 +41,7 @@ dependencies = [
     "pathspec>=0.11.1,<1",
     "pydantic!=2.0.*,!=2.1.*,!=2.2.*,!=2.3.*,!=2.4.*,<3",
     # serve=True dependencies
+    "structlog>=22.0",
     "fastapi>=0.99.1,<1",
     "starlette-exporter>=0.21.0",
     # rest-api-client dependencies
@@ -60,6 +61,11 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
+docs = [
+    "sphinx",
+    "sphinx-rtd-theme",
+    "sphinx-autodoc-typehints",
+]
 test = [
     "pytest<8",
     "pytest-asyncio",
@@ -68,7 +74,7 @@ test = [
     "boto3",
 ]
 dev = [
-    "fal[test]",
+    "fal[docs,test]",
     "openapi-python-client>=0.14.1,<1",
 ]
 

{fal-1.5.2 → fal-1.5.4}/src/fal/_fal_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.5.2'
-__version_tuple__ = version_tuple = (1, 5, 2)
+__version__ = version = '1.5.4'
+__version_tuple__ = version_tuple = (1, 5, 4)

{fal-1.5.2 → fal-1.5.4}/src/fal/api.py

@@ -76,6 +76,7 @@ SERVE_REQUIREMENTS = [
     f"pydantic=={pydantic_version}",
     "uvicorn",
     "starlette_exporter",
+    "structlog",
 ]
 
 

{fal-1.5.2 → fal-1.5.4}/src/fal/app.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 import inspect
 import json
 import os
@@ -8,20 +9,25 @@ import re
 import threading
 import time
 import typing
-from contextlib import asynccontextmanager, contextmanager
+from contextlib import AsyncExitStack, asynccontextmanager, contextmanager
+from dataclasses import dataclass
 from typing import Any, Callable, ClassVar, Literal, TypeVar
 
+import grpc.aio as async_grpc
 import httpx
 from fastapi import FastAPI
+from isolate.server import definitions
 
 import fal.api
 from fal._serialization import include_modules_from
 from fal.api import RouteSignature
-from fal.exceptions import RequestCancelledException
+from fal.exceptions import FalServerlessException, RequestCancelledException
 from fal.logging import get_logger
-from fal.toolkit.file.providers import fal as fal_provider_module
+from fal.toolkit.file import get_lifecycle_preference
+from fal.toolkit.file.providers.fal import GLOBAL_LIFECYCLE_PREFERENCE
 
 REALTIME_APP_REQUIREMENTS = ["websockets", "msgpack"]
+REQUEST_ID_KEY = "x-fal-request-id"
 
 EndpointT = TypeVar("EndpointT", bound=Callable[..., Any])
 logger = get_logger(__name__)
@@ -34,6 +40,48 @@ async def _call_any_fn(fn, *args, **kwargs):
         return fn(*args, **kwargs)
 
 
+async def open_isolate_channel(address: str) -> async_grpc.Channel:
+    _stack = AsyncExitStack()
+    channel = await _stack.enter_async_context(
+        async_grpc.insecure_channel(
+            address,
+            options=[
+                ("grpc.max_send_message_length", -1),
+                ("grpc.max_receive_message_length", -1),
+                ("grpc.min_reconnect_backoff_ms", 0),
+                ("grpc.max_reconnect_backoff_ms", 100),
+                ("grpc.dns_min_time_between_resolutions_ms", 100),
+            ],
+        )
+    )
+
+    channel_status = channel.channel_ready()
+    try:
+        await asyncio.wait_for(channel_status, timeout=1)
+    except asyncio.TimeoutError:
+        await _stack.aclose()
+        raise Exception("Timed out trying to connect to local isolate")
+
+    return channel
+
+
+async def _set_logger_labels(
+    logger_labels: dict[str, str], channel: async_grpc.Channel
+):
+    try:
+        isolate = definitions.IsolateStub(channel)
+        isolate_request = definitions.SetMetadataRequest(
+            # TODO: when submit is shipped, get task_id from an env var
+            task_id="RUN",
+            metadata=definitions.TaskMetadata(logger_labels=logger_labels),
+        )
+        res = isolate.SetMetadata(isolate_request)
+        code = await res.code()
+        assert str(code) == "StatusCode.OK"
+    except BaseException:
+        logger.exception("Failed to set logger labels")
+
+
 def wrap_app(cls: type[App], **kwargs) -> fal.api.IsolatedFunction:
     include_modules_from(cls)
 
@@ -75,6 +123,12 @@ def wrap_app(cls: type[App], **kwargs) -> fal.api.IsolatedFunction:
     return fn
 
 
+@dataclass
+class AppClientError(FalServerlessException):
+    message: str
+    status_code: int
+
+
 class EndpointClient:
     def __init__(self, url, endpoint, signature, timeout: int | None = None):
         self.url = url
@@ -87,12 +141,19 @@ class EndpointClient:
 
     def __call__(self, data):
         with httpx.Client() as client:
+            url = self.url + self.signature.path
             resp = client.post(
                 self.url + self.signature.path,
                 json=data.dict() if hasattr(data, "dict") else dict(data),
                 timeout=self.timeout,
             )
-            resp.raise_for_status()
+            if not resp.is_success:
+                # allow logs to be printed before raising the exception
+                time.sleep(1)
+                raise AppClientError(
+                    f"Failed to POST {url}: {resp.status_code} {resp.text}",
+                    status_code=resp.status_code,
+                )
             resp_dict = resp.json()
 
         if not self.return_type:
@@ -145,12 +206,16 @@ class AppClient:
             with httpx.Client() as client:
                 retries = 100
                 for _ in range(retries):
-                    resp = client.get(info.url + "/health", timeout=60)
+                    url = info.url + "/health"
+                    resp = client.get(url, timeout=60)
 
                     if resp.is_success:
                         break
                     elif resp.status_code not in (500, 404):
-                        resp.raise_for_status()
+                        raise AppClientError(
+                            f"Failed to GET {url}: {resp.status_code} {resp.text}",
+                            status_code=resp.status_code,
+                        )
                     time.sleep(0.1)
 
             client = cls(app_cls, info.url)
@@ -191,6 +256,8 @@ class App(fal.api.BaseServable):
     app_auth: ClassVar[Literal["private", "public", "shared"]] = "private"
     request_timeout: ClassVar[int | None] = None
 
+    isolate_channel: async_grpc.Channel | None = None
+
     def __init_subclass__(cls, **kwargs):
         app_name = kwargs.pop("name", None) or _to_fal_app_name(cls.__name__)
         parent_settings = getattr(cls, "host_kwargs", {})
@@ -266,11 +333,14 @@ class App(fal.api.BaseServable):
 
         @app.middleware("http")
         async def set_global_object_preference(request, call_next):
-            response = await call_next(request)
             try:
-                fal_provider_module.GLOBAL_LIFECYCLE_PREFERENCE = request.headers.get(
-                    "X-Fal-Object-Lifecycle-Preference"
-                )
+                preference_dict = get_lifecycle_preference(request) or {}
+                expiration_duration = preference_dict.get("expiration_duration_seconds")
+                if expiration_duration is not None:
+                    GLOBAL_LIFECYCLE_PREFERENCE.expiration_duration_seconds = int(
+                        expiration_duration
+                    )
+
             except Exception:
                 from fastapi.logger import logger
 
@@ -278,7 +348,26 @@ class App(fal.api.BaseServable):
                     "Failed set a global lifecycle preference %s",
                     self.__class__.__name__,
                 )
-            return response
+
+            return await call_next(request)
+
+        @app.middleware("http")
+        async def set_request_id(request, call_next):
+            if self.isolate_channel is None:
+                grpc_port = os.environ.get("NOMAD_ALLOC_PORT_grpc")
+                self.isolate_channel = await open_isolate_channel(
+                    f"localhost:{grpc_port}"
+                )
+
+            request_id = request.headers.get(REQUEST_ID_KEY)
+            if request_id is not None:
+                await _set_logger_labels(
+                    {"fal_request_id": request_id}, channel=self.isolate_channel
+                )
+            try:
+                return await call_next(request)
+            finally:
+                await _set_logger_labels({}, channel=self.isolate_channel)
 
         @app.exception_handler(RequestCancelledException)
         async def value_error_exception_handler(

{fal-1.5.2 → fal-1.5.4}/src/fal/toolkit/file/file.py

@@ -144,7 +144,7 @@ class File(BaseModel):
 
         fdata = FileData(data, content_type, file_name)
 
-        object_lifecycle_preference = _get_lifecycle_preference(request)
+        object_lifecycle_preference = get_lifecycle_preference(request)
 
         try:
             url = repo.save(fdata, object_lifecycle_preference)
@@ -191,7 +191,7 @@ class File(BaseModel):
         )
 
         content_type = content_type or "application/octet-stream"
-        object_lifecycle_preference = _get_lifecycle_preference(request)
+        object_lifecycle_preference = get_lifecycle_preference(request)
 
         try:
             url, data = repo.save_file(
@@ -274,7 +274,7 @@ class CompressedFile(File):
             shutil.rmtree(self.extract_dir)
 
 
-def _get_lifecycle_preference(request: Request) -> dict[str, str] | None:
+def get_lifecycle_preference(request: Request) -> dict[str, str] | None:
     import json
 
     preference_str = (