modal 0.66.17__py3-none-any.whl → 0.66.44__py3-none-any.whl

modal/_runtime/user_code_imports.py

@@ -0,0 +1,361 @@
+# Copyright Modal Labs 2024
+import importlib
+import typing
+from abc import ABCMeta, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional
+
+import modal._runtime.container_io_manager
+import modal.cls
+import modal.object
+from modal import Function
+from modal._runtime.asgi import (
+    LifespanManager,
+    asgi_app_wrapper,
+    get_ip_address,
+    wait_for_web_server,
+    web_server_proxy,
+    webhook_asgi_app,
+    wsgi_app_wrapper,
+)
+from modal._utils.async_utils import synchronizer
+from modal._utils.function_utils import LocalFunctionError, is_async as get_is_async, is_global_object
+from modal.exception import ExecutionError, InvalidError
+from modal.functions import _Function
+from modal.partial_function import _find_partial_methods_for_user_cls, _PartialFunctionFlags
+from modal_proto import api_pb2
+
+if typing.TYPE_CHECKING:
+    import modal.app
+    import modal.partial_function
+
+
+@dataclass
+class FinalizedFunction:
+    callable: Callable[..., Any]
+    is_async: bool
+    is_generator: bool
+    data_format: int  # api_pb2.DataFormat
+    lifespan_manager: Optional[LifespanManager] = None
+
+
+class Service(metaclass=ABCMeta):
+    """Common interface for singular functions and class-based "services"
+
+    There are differences in the importing/finalization logic, and this
+    "protocol"/abc basically defines a common interface for the two types
+    of "Services" after the point of import.
+    """
+
+    user_cls_instance: Any
+    app: Optional["modal.app._App"]
+    code_deps: Optional[List["modal.object._Object"]]
+
+    @abstractmethod
+    def get_finalized_functions(
+        self, fun_def: api_pb2.Function, container_io_manager: "modal._runtime.container_io_manager.ContainerIOManager"
+    ) -> Dict[str, "FinalizedFunction"]:
+        ...
+
+
+def construct_webhook_callable(
+    user_defined_callable: Callable,
+    webhook_config: api_pb2.WebhookConfig,
+    container_io_manager: "modal._runtime.container_io_manager.ContainerIOManager",
+):
+    # For webhooks, the user function is used to construct an asgi app:
+    if webhook_config.type == api_pb2.WEBHOOK_TYPE_ASGI_APP:
+        # Function returns an asgi_app, which we can use as a callable.
+        return asgi_app_wrapper(user_defined_callable(), container_io_manager)
+
+    elif webhook_config.type == api_pb2.WEBHOOK_TYPE_WSGI_APP:
+        # Function returns an wsgi_app, which we can use as a callable.
+        return wsgi_app_wrapper(user_defined_callable(), container_io_manager)
+
+    elif webhook_config.type == api_pb2.WEBHOOK_TYPE_FUNCTION:
+        # Function is a webhook without an ASGI app. Create one for it.
+        return asgi_app_wrapper(
+            webhook_asgi_app(user_defined_callable, webhook_config.method, webhook_config.web_endpoint_docs),
+            container_io_manager,
+        )
+
+    elif webhook_config.type == api_pb2.WEBHOOK_TYPE_WEB_SERVER:
+        # Function spawns an HTTP web server listening at a port.
+        user_defined_callable()
+
+        # We intentionally try to connect to the external interface instead of the loopback
+        # interface here so users are forced to expose the server. This allows us to potentially
+        # change the implementation to use an external bridge in the future.
+        host = get_ip_address(b"eth0")
+        port = webhook_config.web_server_port
+        startup_timeout = webhook_config.web_server_startup_timeout
+        wait_for_web_server(host, port, timeout=startup_timeout)
+        return asgi_app_wrapper(web_server_proxy(host, port), container_io_manager)
+    else:
+        raise InvalidError(f"Unrecognized web endpoint type {webhook_config.type}")
+
+
+@dataclass
+class ImportedFunction(Service):
+    user_cls_instance: Any
+    app: Optional["modal.app._App"]
+    code_deps: Optional[List["modal.object._Object"]]
+
+    _user_defined_callable: Callable[..., Any]
+
+    def get_finalized_functions(
+        self, fun_def: api_pb2.Function, container_io_manager: "modal._runtime.container_io_manager.ContainerIOManager"
+    ) -> Dict[str, "FinalizedFunction"]:
+        # Check this property before we turn it into a method (overriden by webhooks)
+        is_async = get_is_async(self._user_defined_callable)
+        # Use the function definition for whether this is a generator (overriden by webhooks)
+        is_generator = fun_def.function_type == api_pb2.Function.FUNCTION_TYPE_GENERATOR
+
+        webhook_config = fun_def.webhook_config
+        if not webhook_config.type:
+            # for non-webhooks, the runnable is straight forward:
+            return {
+                "": FinalizedFunction(
+                    callable=self._user_defined_callable,
+                    is_async=is_async,
+                    is_generator=is_generator,
+                    data_format=api_pb2.DATA_FORMAT_PICKLE,
+                )
+            }
+
+        web_callable, lifespan_manager = construct_webhook_callable(
+            self._user_defined_callable, fun_def.webhook_config, container_io_manager
+        )
+
+        return {
+            "": FinalizedFunction(
+                callable=web_callable,
+                lifespan_manager=lifespan_manager,
+                is_async=True,
+                is_generator=True,
+                data_format=api_pb2.DATA_FORMAT_ASGI,
+            )
+        }
+
+
+@dataclass
+class ImportedClass(Service):
+    user_cls_instance: Any
+    app: Optional["modal.app._App"]
+    code_deps: Optional[List["modal.object._Object"]]
+
+    _partial_functions: Dict[str, "modal.partial_function._PartialFunction"]
+
+    def get_finalized_functions(
+        self, fun_def: api_pb2.Function, container_io_manager: "modal._runtime.container_io_manager.ContainerIOManager"
+    ) -> Dict[str, "FinalizedFunction"]:
+        finalized_functions = {}
+        for method_name, partial in self._partial_functions.items():
+            partial = synchronizer._translate_in(partial)  # ugly
+            user_func = partial.raw_f
+            # Check this property before we turn it into a method (overriden by webhooks)
+            is_async = get_is_async(user_func)
+            # Use the function definition for whether this is a generator (overriden by webhooks)
+            is_generator = partial.is_generator
+            webhook_config = partial.webhook_config
+
+            bound_func = user_func.__get__(self.user_cls_instance)
+
+            if not webhook_config or webhook_config.type == api_pb2.WEBHOOK_TYPE_UNSPECIFIED:
+                # for non-webhooks, the runnable is straight forward:
+                finalized_function = FinalizedFunction(
+                    callable=bound_func,
+                    is_async=is_async,
+                    is_generator=is_generator,
+                    data_format=api_pb2.DATA_FORMAT_PICKLE,
+                )
+            else:
+                web_callable, lifespan_manager = construct_webhook_callable(
+                    bound_func, webhook_config, container_io_manager
+                )
+                finalized_function = FinalizedFunction(
+                    callable=web_callable,
+                    lifespan_manager=lifespan_manager,
+                    is_async=True,
+                    is_generator=True,
+                    data_format=api_pb2.DATA_FORMAT_ASGI,
+                )
+            finalized_functions[method_name] = finalized_function
+        return finalized_functions
+
+
+def get_user_class_instance(
+    cls: typing.Union[type, modal.cls.Cls], args: typing.Tuple, kwargs: Dict[str, Any]
+) -> typing.Any:
+    """Returns instance of the underlying class to be used as the `self`
+
+    The input `cls` can either be the raw Python class the user has declared ("user class"),
+    or an @app.cls-decorated version of it which is a modal.Cls-instance wrapping the user class.
+    """
+    if isinstance(cls, modal.cls.Cls):
+        # globally @app.cls-decorated class
+        modal_obj: modal.cls.Obj = cls(*args, **kwargs)
+        modal_obj.entered = True  # ugly but prevents .local() from triggering additional enter-logic
+        # TODO: unify lifecycle logic between .local() and container_entrypoint
+        user_cls_instance = modal_obj._cached_user_cls_instance()
+    else:
+        # undecorated class (non-global decoration or serialized)
+        user_cls_instance = cls(*args, **kwargs)
+
+    return user_cls_instance
+
+
+def import_single_function_service(
+    function_def: api_pb2.Function,
+    ser_cls,  # used only for @build functions
+    ser_fun,
+    cls_args,  #  used only for @build functions
+    cls_kwargs,  #  used only for @build functions
+) -> Service:
+    """Imports a function dynamically, and locates the app.
+
+    This is somewhat complex because we're dealing with 3 quite different type of functions:
+    1. Functions defined in global scope and decorated in global scope (Function objects)
+    2. Functions defined in global scope but decorated elsewhere (these will be raw callables)
+    3. Serialized functions
+
+    In addition, we also need to handle
+    * Normal functions
+    * Methods on classes (in which case we need to instantiate the object)
+
+    This helper also handles web endpoints, ASGI/WSGI servers, and HTTP servers.
+
+    In order to locate the app, we try two things:
+    * If the function is a Function, we can get the app directly from it
+    * Otherwise, use the app name and look it up from a global list of apps: this
+      typically only happens in case 2 above, or in sometimes for case 3
+
+    Note that `import_function` is *not* synchronized, because we need it to run on the main
+    thread. This is so that any user code running in global scope (which executes as a part of
+    the import) runs on the right thread.
+    """
+    user_defined_callable: Callable
+    function: Optional[_Function] = None
+    code_deps: Optional[List["modal.object._Object"]] = None
+    active_app: Optional[modal.app._App] = None
+
+    if ser_fun is not None:
+        # This is a serialized function we already fetched from the server
+        cls, user_defined_callable = ser_cls, ser_fun
+    else:
+        # Load the module dynamically
+        module = importlib.import_module(function_def.module_name)
+        qual_name: str = function_def.function_name
+
+        if not is_global_object(qual_name):
+            raise LocalFunctionError("Attempted to load a function defined in a function scope")
+
+        parts = qual_name.split(".")
+        if len(parts) == 1:
+            # This is a function
+            cls = None
+            f = getattr(module, qual_name)
+            if isinstance(f, Function):
+                function = synchronizer._translate_in(f)
+                user_defined_callable = function.get_raw_f()
+                active_app = function._app
+            else:
+                user_defined_callable = f
+        elif len(parts) == 2:
+            # As of v0.63 - this path should only be triggered by @build class builder methods
+            assert not function_def.use_method_name  # new "placeholder methods" should not be invoked directly!
+            assert function_def.is_builder_function
+            cls_name, fun_name = parts
+            cls = getattr(module, cls_name)
+            if isinstance(cls, modal.cls.Cls):
+                # The cls decorator is in global scope
+                _cls = synchronizer._translate_in(cls)
+                user_defined_callable = _cls._callables[fun_name]
+                function = _cls._method_functions.get(fun_name)
+                active_app = _cls._app
+            else:
+                # This is a raw class
+                user_defined_callable = getattr(cls, fun_name)
+        else:
+            raise InvalidError(f"Invalid function qualname {qual_name}")
+
+    # Instantiate the class if it's defined
+    if cls:
+        # This code is only used for @build methods on classes
+        user_cls_instance = get_user_class_instance(cls, cls_args, cls_kwargs)
+        # Bind the function to the instance as self (using the descriptor protocol!)
+        user_defined_callable = user_defined_callable.__get__(user_cls_instance)
+    else:
+        user_cls_instance = None
+
+    if function:
+        code_deps = function.deps(only_explicit_mounts=True)
+
+    return ImportedFunction(
+        user_cls_instance,
+        active_app,
+        code_deps,
+        user_defined_callable,
+    )
+
+
+def import_class_service(
+    function_def: api_pb2.Function,
+    ser_cls,
+    cls_args,
+    cls_kwargs,
+) -> Service:
+    """
+    This imports a full class to be able to execute any @method or webhook decorated methods.
+
+    See import_function.
+    """
+    active_app: Optional["modal.app._App"]
+    code_deps: Optional[List["modal.object._Object"]]
+    cls: typing.Union[type, modal.cls.Cls]
+
+    if function_def.definition_type == api_pb2.Function.DEFINITION_TYPE_SERIALIZED:
+        assert ser_cls is not None
+        cls = ser_cls
+    else:
+        # Load the module dynamically
+        module = importlib.import_module(function_def.module_name)
+        qual_name: str = function_def.function_name
+
+        if not is_global_object(qual_name):
+            raise LocalFunctionError("Attempted to load a class defined in a function scope")
+
+        parts = qual_name.split(".")
+        if not (
+            len(parts) == 2 and parts[1] == "*"
+        ):  # the "function name" of a class service "function placeholder" is expected to be "ClassName.*"
+            raise ExecutionError(
+                f"Internal error: Invalid 'service function' identifier {qual_name}. Please contact Modal support"
+            )
+
+        assert not function_def.use_method_name  # new "placeholder methods" should not be invoked directly!
+        cls_name = parts[0]
+        cls = getattr(module, cls_name)
+
+    if isinstance(cls, modal.cls.Cls):
+        # The cls decorator is in global scope
+        _cls = synchronizer._translate_in(cls)
+        method_partials = _cls._get_partial_functions()
+        service_function: _Function = _cls._class_service_function
+        code_deps = service_function.deps(only_explicit_mounts=True)
+        active_app = service_function.app
+    else:
+        # Undecorated user class - find all methods
+        method_partials = _find_partial_methods_for_user_cls(cls, _PartialFunctionFlags.all())
+        code_deps = None
+        active_app = None
+
+    user_cls_instance = get_user_class_instance(cls, cls_args, cls_kwargs)
+
+    return ImportedClass(
+        user_cls_instance,
+        active_app,
+        code_deps,
+        # TODO (elias/deven): instead of using method_partials here we should use a set of api_pb2.MethodDefinition
+        method_partials,
+    )

modal/_utils/function_utils.py

@@ -519,6 +519,16 @@ async def _create_input(
         )
 
 
+def _get_suffix_from_web_url_info(url_info: api_pb2.WebUrlInfo) -> str:
+    if url_info.truncated:
+        suffix = " [grey70](label truncated)[/grey70]"
+    elif url_info.label_stolen:
+        suffix = " [grey70](label stolen)[/grey70]"
+    else:
+        suffix = ""
+    return suffix
+
+
 class FunctionCreationStatus:
     # TODO(michael) this really belongs with other output-related code
     # but moving it here so we can use it when loading a function with output disabled
@@ -547,12 +557,7 @@ class FunctionCreationStatus:
         elif self.response.function.web_url:
             url_info = self.response.function.web_url_info
             # Ensure terms used here match terms used in modal.com/docs/guide/webhook-urls doc.
-            if url_info.truncated:
-                suffix = " [grey70](label truncated)[/grey70]"
-            elif url_info.label_stolen:
-                suffix = " [grey70](label stolen)[/grey70]"
-            else:
-                suffix = ""
+            suffix = _get_suffix_from_web_url_info(url_info)
             # TODO: this is only printed when we're showing progress. Maybe move this somewhere else.
             web_url = self.response.handle_metadata.web_url
             self.status_row.finish(
@@ -563,8 +568,23 @@ class FunctionCreationStatus:
             for custom_domain in self.response.function.custom_domain_info:
                 custom_domain_status_row = self.resolver.add_status_row()
                 custom_domain_status_row.finish(
-                    f"Custom domain for {self.tag} => [magenta underline]"
-                    f"{custom_domain.url}[/magenta underline]{suffix}"
+                    f"Custom domain for {self.tag} => [magenta underline]" f"{custom_domain.url}[/magenta underline]"
                 )
         else:
             self.status_row.finish(f"Created function {self.tag}.")
+            if self.response.function.method_definitions_set:
+                for method_definition in self.response.function.method_definitions.values():
+                    if method_definition.web_url:
+                        url_info = method_definition.web_url_info
+                        suffix = _get_suffix_from_web_url_info(url_info)
+                        class_web_endpoint_method_status_row = self.resolver.add_status_row()
+                        class_web_endpoint_method_status_row.finish(
+                            f"Created web endpoint for {method_definition.function_name} => [magenta underline]"
+                            f"{method_definition.web_url}[/magenta underline]{suffix}"
+                        )
+                        for custom_domain in method_definition.custom_domain_info:
+                            custom_domain_status_row = self.resolver.add_status_row()
+                            custom_domain_status_row.finish(
+                                f"Custom domain for {method_definition.function_name} => [magenta underline]"
+                                f"{custom_domain.url}[/magenta underline]"
+                            )

modal/_utils/grpc_testing.py

@@ -52,7 +52,7 @@ def patch_mock_servicer(cls):
         ctx = InterceptionContext()
         servicer.interception_context = ctx
         yield ctx
-        ctx.assert_responses_consumed()
+        ctx._assert_responses_consumed()
         servicer.interception_context = None
 
     cls.intercept = intercept
@@ -64,7 +64,7 @@ def patch_mock_servicer(cls):
                 ctx = servicer_self.interception_context
                 if ctx:
                     intercepted_stream = await InterceptedStream(ctx, method_name, stream).initialize()
-                    custom_responder = ctx.next_custom_responder(method_name, intercepted_stream.request_message)
+                    custom_responder = ctx._next_custom_responder(method_name, intercepted_stream.request_message)
                     if custom_responder:
                         return await custom_responder(servicer_self, intercepted_stream)
                     else:
@@ -105,19 +105,23 @@ class InterceptionContext:
         self.custom_responses: Dict[str, List[Tuple[Callable[[Any], bool], List[Any]]]] = defaultdict(list)
         self.custom_defaults: Dict[str, Callable[["MockClientServicer", grpclib.server.Stream], Awaitable[None]]] = {}
 
-    def add_recv(self, method_name: str, msg):
-        self.calls.append((method_name, msg))
-
     def add_response(
         self, method_name: str, first_payload, *, request_filter: Callable[[Any], bool] = lambda req: True
     ):
-        # adds one response to a queue of responses for requests of the specified type
+        """Adds one response payload to an expected queue of responses for a method.
+
+        These responses will be used once each instead of calling the MockServicer's
+        implementation of the method.
+
+        The interception context will throw an exception on exit if not all of the added
+        responses have been consumed.
+        """
         self.custom_responses[method_name].append((request_filter, [first_payload]))
 
     def set_responder(
         self, method_name: str, responder: Callable[["MockClientServicer", grpclib.server.Stream], Awaitable[None]]
     ):
-        """Replace the default responder method. E.g.
+        """Replace the default responder from the MockClientServicer with a custom implementation
 
         ```python notest
         def custom_responder(servicer, stream):
@@ -128,11 +132,28 @@ class InterceptionContext:
             ctx.set_responder("SomeMethod", custom_responder)
         ```
 
-        Responses added via `.add_response()` take precedence.
+        Responses added via `.add_response()` take precedence over the use of this replacement
         """
         self.custom_defaults[method_name] = responder
 
-    def next_custom_responder(self, method_name, request):
+    def pop_request(self, method_name):
+        # fast forward to the next request of type method_name
+        # dropping any preceding requests if there is a match
+        # returns the payload of the request
+        for i, (_method_name, msg) in enumerate(self.calls):
+            if _method_name == method_name:
+                self.calls = self.calls[i + 1 :]
+                return msg
+
+        raise KeyError(f"No message of that type in call list: {self.calls}")
+
+    def get_requests(self, method_name: str) -> List[Any]:
+        return [msg for _method_name, msg in self.calls if _method_name == method_name]
+
+    def _add_recv(self, method_name: str, msg):
+        self.calls.append((method_name, msg))
+
+    def _next_custom_responder(self, method_name, request):
         method_responses = self.custom_responses[method_name]
         for i, (request_filter, response_messages) in enumerate(method_responses):
             try:
@@ -159,7 +180,7 @@ class InterceptionContext:
 
         return responder
 
-    def assert_responses_consumed(self):
+    def _assert_responses_consumed(self):
         unconsumed = []
         for method_name, queued_responses in self.custom_responses.items():
             unconsumed += [method_name] * len(queued_responses)
@@ -167,23 +188,9 @@ class InterceptionContext:
         if unconsumed:
             raise ResponseNotConsumed(unconsumed)
 
-    def pop_request(self, method_name):
-        # fast forward to the next request of type method_name
-        # dropping any preceding requests if there is a match
-        # returns the payload of the request
-        for i, (_method_name, msg) in enumerate(self.calls):
-            if _method_name == method_name:
-                self.calls = self.calls[i + 1 :]
-                return msg
-
-        raise KeyError(f"No message of that type in call list: {self.calls}")
-
-    def get_requests(self, method_name: str) -> List[Any]:
-        return [msg for _method_name, msg in self.calls if _method_name == method_name]
-
 
 class InterceptedStream:
-    def __init__(self, interception_context, method_name, stream):
+    def __init__(self, interception_context: InterceptionContext, method_name: str, stream):
         self.interception_context = interception_context
         self.method_name = method_name
         self.stream = stream
@@ -200,7 +207,7 @@ class InterceptedStream:
             return ret
 
         msg = await self.stream.recv_message()
-        self.interception_context.add_recv(self.method_name, msg)
+        self.interception_context._add_recv(self.method_name, msg)
         return msg
 
     async def send_message(self, msg):

modal/app.py

@@ -1,6 +1,5 @@
 # Copyright Modal Labs 2022
 import inspect
-import os
 import typing
 import warnings
 from pathlib import PurePosixPath
@@ -42,7 +41,6 @@ from .image import _Image
 from .mount import _Mount
 from .network_file_system import _NetworkFileSystem
 from .object import _get_environment_name, _Object
-from .output import _get_output_manager, enable_output
 from .partial_function import (
     PartialFunction,
     _find_partial_methods_for_user_cls,
@@ -141,25 +139,9 @@ def f(x, y):
 ```
 """
 
-_enable_output_warning = """\
-Note that output will soon not be be printed with `app.run`.
-
-If you want to print output, use `modal.enable_output()`:
-
-```python
-with modal.enable_output():
-    with app.run():
-        ...
-```
-
-If you don't want output, and you want to to suppress this warning,
-use `app.run(..., show_progress=False)`.
-"""
-
 
 class _App:
-    """A Modal app (prior to April 2024 a "stub") is a group of functions and classes
-    deployed together.
+    """A Modal App is a group of functions and classes that are deployed together.
 
     The app serves at least three purposes:
 
@@ -447,32 +429,16 @@ class _App:
 
         # See Github discussion here: https://github.com/modal-labs/modal-client/pull/2030#issuecomment-2237266186
 
-        auto_enable_output = False
-
-        if "MODAL_DISABLE_APP_RUN_OUTPUT_WARNING" not in os.environ:
-            if show_progress is None:
-                if _get_output_manager() is None:
-                    deprecation_warning((2024, 7, 18), _enable_output_warning)
-                    auto_enable_output = True
-            elif show_progress is True:
-                if _get_output_manager() is None:
-                    deprecation_warning((2024, 7, 18), _enable_output_warning)
-                    auto_enable_output = True
-                else:
-                    deprecation_warning((2024, 7, 18), "`show_progress=True` is deprecated and no longer needed.")
-            elif show_progress is False:
-                if _get_output_manager() is not None:
-                    deprecation_warning(
-                        (2024, 7, 18), "`show_progress=False` will have no effect since output is enabled."
-                    )
+        if show_progress is True:
+            deprecation_error(
+                (2024, 11, 20),
+                "`show_progress=True` is no longer supported. Use `with modal.enable_output():` instead.",
+            )
+        elif show_progress is False:
+            deprecation_warning((2024, 11, 20), "`show_progress=False` is deprecated (and has no effect)")
 
-        if auto_enable_output:
-            with enable_output():
-                async with _run_app(self, client=client, detach=detach, interactive=interactive):
-                    yield self
-        else:
-            async with _run_app(self, client=client, detach=detach, interactive=interactive):
-                yield self
+        async with _run_app(self, client=client, detach=detach, interactive=interactive):
+            yield self
 
     def _get_default_image(self):
         if self._image:
@@ -488,7 +454,7 @@ class _App:
             *self._mounts,
         ]
         for function in self.registered_functions.values():
-            all_mounts.extend(function._used_local_mounts)
+            all_mounts.extend(function._serve_mounts)
 
         return [m for m in all_mounts if m.is_local()]
 
@@ -1083,7 +1049,8 @@ App = synchronize_api(_App)
 
 
 class _Stub(_App):
-    """This enables using an "Stub" class instead of "App".
+    """mdmd:hidden
+    This enables using a "Stub" class instead of "App".
 
     For most of Modal's history, the app class was called "Stub", so this exists for
     backwards compatibility, in order to facilitate moving from "Stub" to "App".