modal 0.62.16__py3-none-any.whl → 0.72.11__py3-none-any.whl

modal/app.py

@@ -1,388 +1,1077 @@
 # Copyright Modal Labs 2022
-from typing import TYPE_CHECKING, Dict, List, Optional, TypeVar
+import inspect
+import typing
+import warnings
+from collections.abc import AsyncGenerator, Coroutine, Sequence
+from pathlib import PurePosixPath
+from textwrap import dedent
+from typing import (
+    Any,
+    Callable,
+    ClassVar,
+    Optional,
+    Union,
+    overload,
+)
 
-from google.protobuf.empty_pb2 import Empty
+import typing_extensions
 from google.protobuf.message import Message
-from grpclib import GRPCError, Status
+from synchronicity.async_wrap import asynccontextmanager
 
 from modal_proto import api_pb2
 
-from ._output import OutputManager
-from ._resolver import Resolver
+from ._ipython import is_notebook
 from ._utils.async_utils import synchronize_api
-from ._utils.grpc_utils import get_proto_oneof, retry_transient_errors
+from ._utils.deprecation import deprecation_error, deprecation_warning, renamed_parameter
+from ._utils.function_utils import FunctionInfo, is_global_object, is_method_fn
+from ._utils.grpc_utils import retry_transient_errors
+from ._utils.mount_utils import validate_volumes
 from .client import _Client
+from .cloud_bucket_mount import _CloudBucketMount
+from .cls import _Cls, parameter
 from .config import logger
 from .exception import ExecutionError, InvalidError
-from .object import _Object
+from .functions import Function, _Function
+from .gpu import GPU_T
+from .image import _Image
+from .mount import _Mount
+from .network_file_system import _NetworkFileSystem
+from .object import _get_environment_name, _Object
+from .partial_function import (
+    PartialFunction,
+    _find_partial_methods_for_user_cls,
+    _PartialFunction,
+    _PartialFunctionFlags,
+)
+from .proxy import _Proxy
+from .retries import Retries
+from .running_app import RunningApp
+from .schedule import Schedule
+from .scheduler_placement import SchedulerPlacement
+from .secret import _Secret
+from .volume import _Volume
 
-if TYPE_CHECKING:
-    from .functions import _Function
+_default_image: _Image = _Image.debian_slim()
 
-else:
-    _Function = TypeVar("_Function")
 
+class _LocalEntrypoint:
+    _info: FunctionInfo
+    _app: "_App"
 
-class _LocalApp:
-    _tag_to_object_id: Dict[str, str]
-    _client: _Client
-    _app_id: str
-    _app_page_url: str
-    _environment_name: str
-    _interactive: bool
+    def __init__(self, info: FunctionInfo, app: "_App") -> None:
+        self._info = info
+        self._app = app
 
-    def __init__(
-        self,
-        client: _Client,
-        app_id: str,
-        app_page_url: str,
-        tag_to_object_id: Optional[Dict[str, str]] = None,
-        environment_name: Optional[str] = None,
-        interactive: bool = False,
-    ):
-        """mdmd:hidden This is the app constructor. Users should not call this directly."""
-        self._app_id = app_id
-        self._app_page_url = app_page_url
-        self._client = client
-        self._tag_to_object_id = tag_to_object_id or {}
-        self._environment_name = environment_name
-        self._interactive = interactive
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self._info.raw_f(*args, **kwargs)
 
     @property
-    def client(self) -> _Client:
-        """A reference to the running App's server client."""
-        return self._client
+    def info(self) -> FunctionInfo:
+        return self._info
 
     @property
-    def app_id(self) -> str:
-        """A unique identifier for this running App."""
-        return self._app_id
+    def app(self) -> "_App":
+        return self._app
 
     @property
-    def is_interactive(self) -> bool:
-        return self._interactive
+    def stub(self) -> "_App":
+        # Deprecated soon, only for backwards compatibility
+        return self._app
+
+
+LocalEntrypoint = synchronize_api(_LocalEntrypoint)
+
+
+def check_sequence(items: typing.Sequence[typing.Any], item_type: type[typing.Any], error_msg: str) -> None:
+    if not isinstance(items, (list, tuple)):
+        raise InvalidError(error_msg)
+    if not all(isinstance(v, item_type) for v in items):
+        raise InvalidError(error_msg)
+
+
+CLS_T = typing.TypeVar("CLS_T", bound=type[Any])
+
+
+P = typing_extensions.ParamSpec("P")
+ReturnType = typing.TypeVar("ReturnType")
+OriginalReturnType = typing.TypeVar("OriginalReturnType")
+
+
+class _FunctionDecoratorType:
+    @overload
+    def __call__(
+        self, func: PartialFunction[P, ReturnType, OriginalReturnType]
+    ) -> Function[P, ReturnType, OriginalReturnType]:
+        ...  # already wrapped by a modal decorator, e.g. web_endpoint
+
+    @overload
+    def __call__(
+        self, func: Callable[P, Coroutine[Any, Any, ReturnType]]
+    ) -> Function[P, ReturnType, Coroutine[Any, Any, ReturnType]]:
+        ...  # decorated async function
+
+    @overload
+    def __call__(self, func: Callable[P, ReturnType]) -> Function[P, ReturnType, ReturnType]:
+        ...  # decorated non-async function
+
+    def __call__(self, func):
+        ...
+
+
+_app_attr_error = """\
+App assignments of the form `app.x` or `app["x"]` are deprecated!
+
+The only use cases for these assignments is in conjunction with `.new()`, which is now
+in itself deprecated. If you are constructing objects with `.from_name(...)`, there is no
+need to assign those objects to the app. Example:
 
-    async def _create_all_objects(
+```python
+d = modal.Dict.from_name("my-dict", create_if_missing=True)
+
+@app.function()
+def f(x, y):
+    d[x] = y  # Refer to d in global scope
+```
+"""
+
+
+class _App:
+    """A Modal App is a group of functions and classes that are deployed together.
+
+    The app serves at least three purposes:
+
+    * A unit of deployment for functions and classes.
+    * Syncing of identities of (primarily) functions and classes across processes
+      (your local Python interpreter and every Modal container active in your application).
+    * Manage log collection for everything that happens inside your code.
+
+    **Registering functions with an app**
+
+    The most common way to explicitly register an Object with an app is through the
+    `@app.function()` decorator. It both registers the annotated function itself and
+    other passed objects, like schedules and secrets, with the app:
+
+    ```python
+    import modal
+
+    app = modal.App()
+
+    @app.function(
+        secrets=[modal.Secret.from_name("some_secret")],
+        schedule=modal.Period(days=1),
+    )
+    def foo():
+        pass
+    ```
+
+    In this example, the secret and schedule are registered with the app.
+    """
+
+    _all_apps: ClassVar[dict[Optional[str], list["_App"]]] = {}
+    _container_app: ClassVar[Optional["_App"]] = None
+
+    _name: Optional[str]
+    _description: Optional[str]
+    _functions: dict[str, _Function]
+    _classes: dict[str, _Cls]
+
+    _image: Optional[_Image]
+    _mounts: Sequence[_Mount]
+    _secrets: Sequence[_Secret]
+    _volumes: dict[Union[str, PurePosixPath], _Volume]
+    _web_endpoints: list[str]  # Used by the CLI
+    _local_entrypoints: dict[str, _LocalEntrypoint]
+
+    # Running apps only (container apps or running local)
+    _app_id: Optional[str]  # Kept after app finishes
+    _running_app: Optional[RunningApp]  # Various app info
+    _client: Optional[_Client]
+
+    def __init__(
         self,
-        indexed_objects: Dict[str, _Object],
-        new_app_state: int,
-        environment_name: str,
-        output_mgr: Optional[OutputManager] = None,
-    ):  # api_pb2.AppState.V
-        """Create objects that have been defined but not created on the server."""
-        if not self._client.authenticated:
-            raise ExecutionError("Objects cannot be created with an unauthenticated client")
-
-        resolver = Resolver(
-            self._client,
-            output_mgr=output_mgr,
-            environment_name=environment_name,
-            app_id=self.app_id,
-        )
-        with resolver.display():
-            # Get current objects, and reset all objects
-            tag_to_object_id = self._tag_to_object_id
-            self._tag_to_object_id = {}
-
-            # Assign all objects
-            for tag, obj in indexed_objects.items():
-                # Reset object_id in case the app runs twice
-                # TODO(erikbern): clean up the interface
-                obj._unhydrate()
-
-            # Preload all functions to make sure they have ids assigned before they are loaded.
-            # This is important to make sure any enclosed function handle references in serialized
-            # functions have ids assigned to them when the function is serialized.
-            # Note: when handles/objs are merged, all objects will need to get ids pre-assigned
-            # like this in order to be referrable within serialized functions
-            for tag, obj in indexed_objects.items():
-                existing_object_id = tag_to_object_id.get(tag)
-                # Note: preload only currently implemented for Functions, returns None otherwise
-                # this is to ensure that directly referenced functions from the global scope has
-                # ids associated with them when they are serialized into other functions
-                await resolver.preload(obj, existing_object_id)
-                if obj.object_id is not None:
-                    tag_to_object_id[tag] = obj.object_id
-
-            for tag, obj in indexed_objects.items():
-                existing_object_id = tag_to_object_id.get(tag)
-                await resolver.load(obj, existing_object_id)
-                self._tag_to_object_id[tag] = obj.object_id
-
-        # Create the app (and send a list of all tagged obs)
-        # TODO(erikbern): we should delete objects from a previous version that are no longer needed
-        # We just delete them from the app, but the actual objects will stay around
-        indexed_object_ids = self._tag_to_object_id
-        assert indexed_object_ids == self._tag_to_object_id
-        all_objects = resolver.objects()
-
-        unindexed_object_ids = list(set(obj.object_id for obj in all_objects) - set(self._tag_to_object_id.values()))
-        req_set = api_pb2.AppSetObjectsRequest(
-            app_id=self._app_id,
-            indexed_object_ids=indexed_object_ids,
-            unindexed_object_ids=unindexed_object_ids,
-            new_app_state=new_app_state,  # type: ignore
-        )
-        await retry_transient_errors(self._client.stub.AppSetObjects, req_set)
+        name: Optional[str] = None,
+        *,
+        image: Optional[_Image] = None,  # default image for all functions (default is `modal.Image.debian_slim()`)
+        mounts: Sequence[_Mount] = [],  # default mounts for all functions
+        secrets: Sequence[_Secret] = [],  # default secrets for all functions
+        volumes: dict[Union[str, PurePosixPath], _Volume] = {},  # default volumes for all functions
+    ) -> None:
+        """Construct a new app, optionally with default image, mounts, secrets, or volumes.
 
-    async def disconnect(
-        self, reason: "Optional[api_pb2.AppDisconnectReason.ValueType]" = None, exc_str: Optional[str] = None
-    ):
-        """Tell the server the client has disconnected for this app. Terminates all running tasks
-        for ephemeral apps."""
+        ```python notest
+        image = modal.Image.debian_slim().pip_install(...)
+        secret = modal.Secret.from_name("my-secret")
+        volume = modal.Volume.from_name("my-data")
+        app = modal.App(image=image, secrets=[secret], volumes={"/mnt/data": volume})
+        ```
+        """
+        if name is not None and not isinstance(name, str):
+            raise InvalidError("Invalid value for `name`: Must be string.")
 
-        if exc_str:
-            exc_str = exc_str[:1000]  # Truncate to 1000 chars
+        self._name = name
+        self._description = name
 
-        logger.debug("Sending app disconnect/stop request")
-        req_disconnect = api_pb2.AppClientDisconnectRequest(app_id=self._app_id, reason=reason, exception=exc_str)
-        await retry_transient_errors(self._client.stub.AppClientDisconnect, req_disconnect)
-        logger.debug("App disconnected")
+        check_sequence(mounts, _Mount, "`mounts=` has to be a list or tuple of Mount objects")
+        check_sequence(secrets, _Secret, "`secrets=` has to be a list or tuple of Secret objects")
+        validate_volumes(volumes)
 
-    async def stop(self):
-        """Tell the server to stop this app, terminating all running tasks."""
-        req_disconnect = api_pb2.AppStopRequest(app_id=self._app_id, source=api_pb2.APP_STOP_SOURCE_PYTHON_CLIENT)
-        await retry_transient_errors(self._client.stub.AppStop, req_disconnect)
+        if image is not None and not isinstance(image, _Image):
+            raise InvalidError("image has to be a modal Image or AioImage object")
 
-    def log_url(self):
-        """URL link to a running app's logs page in the Modal dashboard."""
-        return self._app_page_url
+        self._functions = {}
+        self._classes = {}
+        self._image = image
+        self._mounts = mounts
+        self._secrets = secrets
+        self._volumes = volumes
+        self._local_entrypoints = {}
+        self._web_endpoints = []
 
-    @staticmethod
-    async def _init_existing(client: _Client, existing_app_id: str) -> "_LocalApp":
-        # Get all the objects first
-        obj_req = api_pb2.AppGetObjectsRequest(app_id=existing_app_id)
-        obj_resp = await retry_transient_errors(client.stub.AppGetObjects, obj_req)
-        app_page_url = f"https://modal.com/apps/{existing_app_id}"  # TODO (elias): this should come from the backend
-        object_ids = {item.tag: item.object.object_id for item in obj_resp.items}
-        return _LocalApp(client, existing_app_id, app_page_url, tag_to_object_id=object_ids)
+        self._app_id = None
+        self._running_app = None  # Set inside container, OR during the time an app is running locally
+        self._client = None
 
-    @staticmethod
-    async def _init_new(
-        client: _Client,
-        description: str,
-        app_state: int,
-        environment_name: str = "",
-        interactive=False,
-    ) -> "_LocalApp":
-        app_req = api_pb2.AppCreateRequest(
-            description=description,
-            environment_name=environment_name,
-            app_state=app_state,
-        )
-        app_resp = await retry_transient_errors(client.stub.AppCreate, app_req)
-        app_page_url = app_resp.app_logs_url
-        logger.debug(f"Created new app with id {app_resp.app_id}")
-        return _LocalApp(
-            client, app_resp.app_id, app_page_url, environment_name=environment_name, interactive=interactive
-        )
+        # Register this app. This is used to look up the app in the container, when we can't get it from the function
+        _App._all_apps.setdefault(self._name, []).append(self)
+
+    @property
+    def name(self) -> Optional[str]:
+        """The user-provided name of the App."""
+        return self._name
+
+    @property
+    def is_interactive(self) -> bool:
+        """Whether the current app for the app is running in interactive mode."""
+        # return self._name
+        if self._running_app:
+            return self._running_app.interactive
+        else:
+            return False
+
+    @property
+    def app_id(self) -> Optional[str]:
+        """Return the app_id of a running or stopped app."""
+        return self._app_id
+
+    @property
+    def description(self) -> Optional[str]:
+        """The App's `name`, if available, or a fallback descriptive identifier."""
+        return self._description
 
     @staticmethod
-    async def _init_from_name(
-        client: _Client,
+    @renamed_parameter((2024, 12, 18), "label", "name")
+    async def lookup(
         name: str,
-        namespace,
-        environment_name: str = "",
-    ):
-        # Look up any existing deployment
-        app_req = api_pb2.AppGetByDeploymentNameRequest(
-            name=name,
-            namespace=namespace,
+        client: Optional[_Client] = None,
+        environment_name: Optional[str] = None,
+        create_if_missing: bool = False,
+    ) -> "_App":
+        """Look up an App with a given name, creating a new App if necessary.
+
+        Note that Apps created through this method will be in a deployed state,
+        but they will not have any associated Functions or Classes. This method
+        is mainly useful for creating an App to associate with a Sandbox:
+
+        ```python
+        app = modal.App.lookup("my-app", create_if_missing=True)
+        modal.Sandbox.create("echo", "hi", app=app)
+        ```
+        """
+        if client is None:
+            client = await _Client.from_env()
+
+        environment_name = _get_environment_name(environment_name)
+
+        request = api_pb2.AppGetOrCreateRequest(
+            app_name=name,
             environment_name=environment_name,
+            object_creation_type=(api_pb2.OBJECT_CREATION_TYPE_CREATE_IF_MISSING if create_if_missing else None),
         )
-        app_resp = await retry_transient_errors(client.stub.AppGetByDeploymentName, app_req)
-        existing_app_id = app_resp.app_id or None
 
-        # Grab the app
-        if existing_app_id is not None:
-            return await _LocalApp._init_existing(client, existing_app_id)
+        response = await retry_transient_errors(client.stub.AppGetOrCreate, request)
+
+        app = _App(name)
+        app._app_id = response.app_id
+        app._client = client
+        app._running_app = RunningApp(response.app_id, interactive=False)
+        return app
+
+    def set_description(self, description: str):
+        self._description = description
+
+    def _validate_blueprint_value(self, key: str, value: Any):
+        if not isinstance(value, _Object):
+            raise InvalidError(f"App attribute `{key}` with value {value!r} is not a valid Modal object")
+
+    def __getitem__(self, tag: str):
+        deprecation_error((2024, 3, 25), _app_attr_error)
+
+    def __setitem__(self, tag: str, obj: _Object):
+        deprecation_error((2024, 3, 25), _app_attr_error)
+
+    def __getattr__(self, tag: str):
+        # TODO(erikbern): remove this method later
+        assert isinstance(tag, str)
+        if tag.startswith("__"):
+            # Hacky way to avoid certain issues, e.g. pickle will try to look this up
+            raise AttributeError(f"App has no member {tag}")
+        if tag not in self._functions or tag not in self._classes:
+            # Primarily to make hasattr work
+            raise AttributeError(f"App has no member {tag}")
+        deprecation_error((2024, 3, 25), _app_attr_error)
+
+    def __setattr__(self, tag: str, obj: _Object):
+        # TODO(erikbern): remove this method later
+        # Note that only attributes defined in __annotations__ are set on the object itself,
+        # everything else is registered on the indexed_objects
+        if tag in self.__annotations__:
+            object.__setattr__(self, tag, obj)
+        elif tag == "image":
+            self._image = obj
         else:
-            return await _LocalApp._init_new(
-                client, name, api_pb2.APP_STATE_INITIALIZING, environment_name=environment_name
-            )
+            deprecation_error((2024, 3, 25), _app_attr_error)
 
-    async def deploy(self, name: str, namespace, public: bool) -> str:
-        """`App.deploy` is deprecated in favor of `modal.runner.deploy_stub`."""
+    @property
+    def image(self) -> _Image:
+        return self._image
 
-        deploy_req = api_pb2.AppDeployRequest(
-            app_id=self.app_id,
-            name=name,
-            namespace=namespace,
-            object_entity="ap",
-            visibility=(api_pb2.APP_DEPLOY_VISIBILITY_PUBLIC if public else api_pb2.APP_DEPLOY_VISIBILITY_WORKSPACE),
-        )
+    @image.setter
+    def image(self, value):
+        self._image = value
+
+    def _uncreate_all_objects(self):
+        # TODO(erikbern): this doesn't unhydrate objects that aren't tagged
+        for obj in self._functions.values():
+            obj._unhydrate()
+        for obj in self._classes.values():
+            obj._unhydrate()
+
+    @asynccontextmanager
+    async def _set_local_app(self, client: _Client, running_app: RunningApp) -> AsyncGenerator[None, None]:
+        self._app_id = running_app.app_id
+        self._running_app = running_app
+        self._client = client
         try:
-            deploy_response = await retry_transient_errors(self._client.stub.AppDeploy, deploy_req)
-        except GRPCError as exc:
-            if exc.status == Status.INVALID_ARGUMENT:
-                raise InvalidError(exc.message)
-            if exc.status == Status.FAILED_PRECONDITION:
-                raise InvalidError(exc.message)
-            raise
-        return deploy_response.url
+            yield
+        finally:
+            self._running_app = None
+            self._client = None
+            self._uncreate_all_objects()
 
+    @asynccontextmanager
+    async def run(
+        self,
+        client: Optional[_Client] = None,
+        show_progress: Optional[bool] = None,
+        detach: bool = False,
+        interactive: bool = False,
+    ) -> AsyncGenerator["_App", None]:
+        """Context manager that runs an app on Modal.
 
-class _ContainerApp:
-    _client: Optional[_Client]
-    _app_id: Optional[str]
-    _environment_name: Optional[str]
-    _tag_to_object_id: Dict[str, str]
-    _object_handle_metadata: Dict[str, Optional[Message]]
-    # if true, there's an active PTY shell session connected to this process.
-    _is_interactivity_enabled: bool
-    _function_def: Optional[api_pb2.Function]
-    _fetching_inputs: bool
-
-    def __init__(self):
-        self._client = None
-        self._app_id = None
-        self._environment_name = None
-        self._tag_to_object_id = {}
-        self._object_handle_metadata = {}
-        self._is_interactivity_enabled = False
-        self._fetching_inputs = True
+        Use this as the main entry point for your Modal application. All calls
+        to Modal functions should be made within the scope of this context
+        manager, and they will correspond to the current app.
+
+        **Example**
+
+        ```python notest
+        with app.run():
+            some_modal_function.remote()
+        ```
+
+        To enable output printing, use `modal.enable_output()`:
+
+        ```python notest
+        with modal.enable_output():
+            with app.run():
+                some_modal_function.remote()
+        ```
+
+        Note that you cannot invoke this in global scope of a file where you have
+        Modal functions or Classes, since that would run the block when the function
+        or class is imported in your containers as well. If you want to run it as
+        your entrypoint, consider wrapping it:
+
+        ```python
+        if __name__ == "__main__":
+            with app.run():
+                some_modal_function.remote()
+        ```
+
+        You can then run your script with:
+
+        ```shell
+        python app_module.py
+        ```
+
+        Note that this method used to return a separate "App" object. This is
+        no longer useful since you can use the app itself for access to all
+        objects. For backwards compatibility reasons, it returns the same app.
+        """
+        from .runner import _run_app  # Defer import of runner.py, which imports a lot from Rich
+
+        # See Github discussion here: https://github.com/modal-labs/modal-client/pull/2030#issuecomment-2237266186
+
+        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)")
+
+        async with _run_app(self, client=client, detach=detach, interactive=interactive):
+            yield self
+
+    def _get_default_image(self):
+        if self._image:
+            return self._image
+        else:
+            return _default_image
+
+    def _get_watch_mounts(self):
+        if not self._running_app:
+            raise ExecutionError("`_get_watch_mounts` requires a running app.")
+
+        all_mounts = [
+            *self._mounts,
+        ]
+        for function in self.registered_functions.values():
+            all_mounts.extend(function._serve_mounts)
+
+        return [m for m in all_mounts if m.is_local()]
+
+    def _add_function(self, function: _Function, is_web_endpoint: bool):
+        if function.tag in self._functions:
+            if not is_notebook():
+                old_function: _Function = self._functions[function.tag]
+                logger.warning(
+                    f"Warning: Tag '{function.tag}' collision!"
+                    " Overriding existing function "
+                    f"[{old_function._info.module_name}].{old_function._info.function_name}"
+                    f" with new function [{function._info.module_name}].{function._info.function_name}"
+                )
+        if function.tag in self._classes:
+            logger.warning(f"Warning: tag {function.tag} exists but is overridden by function")
+
+        if self._running_app:
+            # If this is inside a container, then objects can be defined after app initialization.
+            # So we may have to initialize objects once they get bound to the app.
+            if function.tag in self._running_app.function_ids:
+                object_id: str = self._running_app.function_ids[function.tag]
+                metadata: Message = self._running_app.object_handle_metadata[object_id]
+                function._hydrate(object_id, self._client, metadata)
+
+        self._functions[function.tag] = function
+        if is_web_endpoint:
+            self._web_endpoints.append(function.tag)
+
+    def _add_class(self, tag: str, cls: _Cls):
+        if self._running_app:
+            # If this is inside a container, then objects can be defined after app initialization.
+            # So we may have to initialize objects once they get bound to the app.
+            if tag in self._running_app.class_ids:
+                object_id: str = self._running_app.class_ids[tag]
+                metadata: Message = self._running_app.object_handle_metadata[object_id]
+                cls._hydrate(object_id, self._client, metadata)
+
+        self._classes[tag] = cls
+
+    def _init_container(self, client: _Client, running_app: RunningApp):
+        self._app_id = running_app.app_id
+        self._running_app = running_app
+        self._client = client
+
+        _App._container_app = self
+
+        # Hydrate function objects
+        for tag, object_id in running_app.function_ids.items():
+            if tag in self._functions:
+                obj = self._functions[tag]
+                handle_metadata = running_app.object_handle_metadata[object_id]
+                obj._hydrate(object_id, client, handle_metadata)
+
+        # Hydrate class objects
+        for tag, object_id in running_app.class_ids.items():
+            if tag in self._classes:
+                obj = self._classes[tag]
+                handle_metadata = running_app.object_handle_metadata[object_id]
+                obj._hydrate(object_id, client, handle_metadata)
 
     @property
-    def client(self) -> Optional[_Client]:
-        """A reference to the running App's server client."""
-        return self._client
+    def registered_functions(self) -> dict[str, _Function]:
+        """All modal.Function objects registered on the app."""
+        return self._functions
 
     @property
-    def app_id(self) -> Optional[str]:
-        """A unique identifier for this running App."""
-        return self._app_id
+    def registered_classes(self) -> dict[str, _Function]:
+        """All modal.Cls objects registered on the app."""
+        return self._classes
 
     @property
-    def fetching_inputs(self) -> bool:
-        return self._fetching_inputs
-
-    def associate_stub_container(self, stub):
-        stub._container_app = self
-
-        # Initialize objects on stub
-        stub_objects: dict[str, _Object] = dict(stub.get_objects())
-        for tag, object_id in self._tag_to_object_id.items():
-            obj = stub_objects.get(tag)
-            if obj is not None:
-                handle_metadata = self._object_handle_metadata[object_id]
-                obj._hydrate(object_id, self._client, handle_metadata)
-
-    def _has_object(self, tag: str) -> bool:
-        return tag in self._tag_to_object_id
-
-    def _hydrate_object(self, obj, tag: str):
-        object_id: str = self._tag_to_object_id[tag]
-        metadata: Message = self._object_handle_metadata[object_id]
-        obj._hydrate(object_id, self._client, metadata)
-
-    def hydrate_function_deps(self, function: _Function, dep_object_ids: List[str]):
-        function_deps = function.deps(only_explicit_mounts=True)
-        if len(function_deps) != len(dep_object_ids):
-            raise ExecutionError(
-                f"Function has {len(function_deps)} dependencies"
-                f" but container got {len(dep_object_ids)} object ids."
-            )
-        for object_id, obj in zip(dep_object_ids, function_deps):
-            metadata: Message = self._object_handle_metadata[object_id]
-            obj._hydrate(object_id, self._client, metadata)
+    def registered_entrypoints(self) -> dict[str, _LocalEntrypoint]:
+        """All local CLI entrypoints registered on the app."""
+        return self._local_entrypoints
+
+    @property
+    def indexed_objects(self) -> dict[str, _Object]:
+        deprecation_warning(
+            (2024, 11, 25),
+            "`app.indexed_objects` is deprecated! Use `app.registered_functions` or `app.registered_classes` instead.",
+        )
+        return dict(**self._functions, **self._classes)
+
+    @property
+    def registered_web_endpoints(self) -> list[str]:
+        """Names of web endpoint (ie. webhook) functions registered on the app."""
+        return self._web_endpoints
+
+    def local_entrypoint(
+        self, _warn_parentheses_missing: Any = None, *, name: Optional[str] = None
+    ) -> Callable[[Callable[..., Any]], _LocalEntrypoint]:
+        """Decorate a function to be used as a CLI entrypoint for a Modal App.
+
+        These functions can be used to define code that runs locally to set up the app,
+        and act as an entrypoint to start Modal functions from. Note that regular
+        Modal functions can also be used as CLI entrypoints, but unlike `local_entrypoint`,
+        those functions are executed remotely directly.
+
+        **Example**
+
+        ```python
+        @app.local_entrypoint()
+        def main():
+            some_modal_function.remote()
+        ```
+
+        You can call the function using `modal run` directly from the CLI:
+
+        ```shell
+        modal run app_module.py
+        ```
+
+        Note that an explicit [`app.run()`](/docs/reference/modal.App#run) is not needed, as an
+        [app](/docs/guide/apps) is automatically created for you.
+
+        **Multiple Entrypoints**
+
+        If you have multiple `local_entrypoint` functions, you can qualify the name of your app and function:
+
+        ```shell
+        modal run app_module.py::app.some_other_function
+        ```
+
+        **Parsing Arguments**
+
+        If your entrypoint function take arguments with primitive types, `modal run` automatically parses them as
+        CLI options.
+        For example, the following function can be called with `modal run app_module.py --foo 1 --bar "hello"`:
+
+        ```python
+        @app.local_entrypoint()
+        def main(foo: int, bar: str):
+            some_modal_function.call(foo, bar)
+        ```
+
+        Currently, `str`, `int`, `float`, `bool`, and `datetime.datetime` are supported.
+        Use `modal run app_module.py --help` for more information on usage.
 
-    async def init(
+        """
+        if _warn_parentheses_missing:
+            raise InvalidError("Did you forget parentheses? Suggestion: `@app.local_entrypoint()`.")
+        if name is not None and not isinstance(name, str):
+            raise InvalidError("Invalid value for `name`: Must be string.")
+
+        def wrapped(raw_f: Callable[..., Any]) -> _LocalEntrypoint:
+            info = FunctionInfo(raw_f)
+            tag = name if name is not None else raw_f.__qualname__
+            if tag in self._local_entrypoints:
+                # TODO: get rid of this limitation.
+                raise InvalidError(f"Duplicate local entrypoint name: {tag}. Local entrypoint names must be unique.")
+            entrypoint = self._local_entrypoints[tag] = _LocalEntrypoint(info, self)
+            return entrypoint
+
+        return wrapped
+
+    def function(
         self,
-        client: _Client,
-        app_id: str,
-        environment_name: str = "",
-        function_def: Optional[api_pb2.Function] = None,
-    ):
-        """Used by the container to bootstrap the app and all its objects. Not intended to be called by Modal users."""
-        global _is_container_app
-        _is_container_app = True
+        _warn_parentheses_missing: Any = None,
+        *,
+        image: Optional[_Image] = None,  # The image to run as the container for the function
+        schedule: Optional[Schedule] = None,  # An optional Modal Schedule for the function
+        secrets: Sequence[_Secret] = (),  # Optional Modal Secret objects with environment variables for the container
+        gpu: Union[
+            GPU_T, list[GPU_T]
+        ] = None,  # GPU request as string ("any", "T4", ...), object (`modal.GPU.A100()`, ...), or a list of either
+        serialized: bool = False,  # Whether to send the function over using cloudpickle.
+        mounts: Sequence[_Mount] = (),  # Modal Mounts added to the container
+        network_file_systems: dict[
+            Union[str, PurePosixPath], _NetworkFileSystem
+        ] = {},  # Mountpoints for Modal NetworkFileSystems
+        volumes: dict[
+            Union[str, PurePosixPath], Union[_Volume, _CloudBucketMount]
+        ] = {},  # Mount points for Modal Volumes & CloudBucketMounts
+        allow_cross_region_volumes: bool = False,  # Whether using network file systems from other regions is allowed.
+        # Specify, in fractional CPU cores, how many CPU cores to request.
+        # Or, pass (request, limit) to additionally specify a hard limit in fractional CPU cores.
+        # CPU throttling will prevent a container from exceeding its specified limit.
+        cpu: Optional[Union[float, tuple[float, float]]] = None,
+        # Specify, in MiB, a memory request which is the minimum memory required.
+        # Or, pass (request, limit) to additionally specify a hard limit in MiB.
+        memory: Optional[Union[int, tuple[int, int]]] = None,
+        ephemeral_disk: Optional[int] = None,  # Specify, in MiB, the ephemeral disk size for the Function.
+        proxy: Optional[_Proxy] = None,  # Reference to a Modal Proxy to use in front of this function.
+        retries: Optional[Union[int, Retries]] = None,  # Number of times to retry each input in case of failure.
+        concurrency_limit: Optional[
+            int
+        ] = None,  # An optional maximum number of concurrent containers running the function (keep_warm sets minimum).
+        allow_concurrent_inputs: Optional[int] = None,  # Number of inputs the container may fetch to run concurrently.
+        container_idle_timeout: Optional[int] = None,  # Timeout for idle containers waiting for inputs to shut down.
+        timeout: Optional[int] = None,  # Maximum execution time of the function in seconds.
+        keep_warm: Optional[
+            int
+        ] = None,  # An optional minimum number of containers to always keep warm (use concurrency_limit for maximum).
+        name: Optional[str] = None,  # Sets the Modal name of the function within the app
+        is_generator: Optional[
+            bool
+        ] = None,  # Set this to True if it's a non-generator function returning a [sync/async] generator object
+        cloud: Optional[str] = None,  # Cloud provider to run the function on. Possible values are aws, gcp, oci, auto.
+        region: Optional[Union[str, Sequence[str]]] = None,  # Region or regions to run the function on.
+        enable_memory_snapshot: bool = False,  # Enable memory checkpointing for faster cold starts.
+        block_network: bool = False,  # Whether to block network access
+        # Maximum number of inputs a container should handle before shutting down.
+        # With `max_inputs = 1`, containers will be single-use.
+        max_inputs: Optional[int] = None,
+        i6pn: Optional[bool] = None,  # Whether to enable IPv6 container networking within the region.
+        # Parameters below here are experimental. Use with caution!
+        _experimental_scheduler_placement: Optional[
+            SchedulerPlacement
+        ] = None,  # Experimental controls over fine-grained scheduling (alpha).
+        _experimental_buffer_containers: Optional[int] = None,  # Number of additional, idle containers to keep around.
+        _experimental_proxy_ip: Optional[str] = None,  # IP address of proxy
+        _experimental_custom_scaling_factor: Optional[float] = None,  # Custom scaling factor
+    ) -> _FunctionDecoratorType:
+        """Decorator to register a new Modal [Function](/docs/reference/modal.Function) with this App."""
+        if isinstance(_warn_parentheses_missing, _Image):
+            # Handle edge case where maybe (?) some users passed image as a positional arg
+            raise InvalidError("`image` needs to be a keyword argument: `@app.function(image=image)`.")
+        if _warn_parentheses_missing:
+            raise InvalidError("Did you forget parentheses? Suggestion: `@app.function()`.")
 
-        self._client = client
-        self._app_id = app_id
-        self._environment_name = environment_name
-        self._function_def = function_def
-        self._tag_to_object_id = {}
-        self._object_handle_metadata = {}
-        req = api_pb2.AppGetObjectsRequest(app_id=app_id, include_unindexed=True)
-        resp = await retry_transient_errors(client.stub.AppGetObjects, req)
-        logger.debug(f"AppGetObjects received {len(resp.items)} objects for app {app_id}")
-        for item in resp.items:
-            handle_metadata: Optional[Message] = get_proto_oneof(item.object, "handle_metadata_oneof")
-            self._object_handle_metadata[item.object.object_id] = handle_metadata
-            logger.debug(f"Setting metadata for {item.object.object_id} ({item.tag})")
-            if item.tag:
-                self._tag_to_object_id[item.tag] = item.object.object_id
+        if image is None:
+            image = self._get_default_image()
 
-    @staticmethod
-    def _reset_container():
-        # Just used for tests
-        global _is_container_app, _container_app
-        _is_container_app = False
-        _container_app.__init__()  # type: ignore
+        secrets = [*self._secrets, *secrets]
+
+        def wrapped(
+            f: Union[_PartialFunction, Callable[..., Any], None],
+        ) -> _Function:
+            nonlocal keep_warm, is_generator, cloud, serialized
 
-    def stop_fetching_inputs(self):
-        self._fetching_inputs = False
+            # Check if the decorated object is a class
+            if inspect.isclass(f):
+                raise TypeError(
+                    "The `@app.function` decorator cannot be used on a class. Please use `@app.cls` instead."
+                )
 
+            if isinstance(f, _PartialFunction):
+                # typically for @function-wrapped @web_endpoint, @asgi_app, or @batched
+                f.wrapped = True
 
-LocalApp = synchronize_api(_LocalApp)
-ContainerApp = synchronize_api(_ContainerApp)
+                # but we don't support @app.function wrapping a method.
+                if is_method_fn(f.raw_f.__qualname__):
+                    raise InvalidError(
+                        "The `@app.function` decorator cannot be used on class methods. "
+                        "Swap with `@modal.method` or `@modal.web_endpoint`, or drop the `@app.function` decorator. "
+                        "Example: "
+                        "\n\n"
+                        "```python\n"
+                        "@app.cls()\n"
+                        "class MyClass:\n"
+                        "    @modal.web_endpoint()\n"
+                        "    def f(self, x):\n"
+                        "        ...\n"
+                        "```\n"
+                    )
+                i6pn_enabled = i6pn or (f.flags & _PartialFunctionFlags.CLUSTERED)
+                cluster_size = f.cluster_size  # Experimental: Clustered functions
 
-_is_container_app = False
-_container_app = _ContainerApp()
-container_app = synchronize_api(_container_app)
-assert isinstance(container_app, ContainerApp)
+                info = FunctionInfo(f.raw_f, serialized=serialized, name_override=name)
+                raw_f = f.raw_f
+                webhook_config = f.webhook_config
+                is_generator = f.is_generator
+                keep_warm = f.keep_warm or keep_warm
+                batch_max_size = f.batch_max_size
+                batch_wait_ms = f.batch_wait_ms
+            else:
+                if not is_global_object(f.__qualname__) and not serialized:
+                    raise InvalidError(
+                        dedent(
+                            """
+                            The `@app.function` decorator must apply to functions in global scope,
+                            unless `serialize=True` is set.
+                            If trying to apply additional decorators, they may need to use `functools.wraps`.
+                            """
+                        )
+                    )
 
+                if is_method_fn(f.__qualname__):
+                    raise InvalidError(
+                        dedent(
+                            """
+                            The `@app.function` decorator cannot be used on class methods.
+                            Please use `@app.cls` with `@modal.method` instead. Example:
 
-async def _interact(client: Optional[_Client] = None) -> None:
-    if _container_app._is_interactivity_enabled:
-        # Currently, interactivity is enabled forever
-        return
-    _container_app._is_interactivity_enabled = True
+                            ```python
+                            @app.cls()
+                            class MyClass:
+                                @modal.method()
+                                def f(self, x):
+                                    ...
+                            ```
+                            """
+                        )
+                    )
 
-    if not client:
-        client = await _Client.from_env()
+                info = FunctionInfo(f, serialized=serialized, name_override=name)
+                webhook_config = None
+                batch_max_size = None
+                batch_wait_ms = None
+                raw_f = f
 
-    if client.client_type != api_pb2.CLIENT_TYPE_CONTAINER:
-        raise InvalidError("Interactivity only works inside a Modal Container.")
+                cluster_size = None  # Experimental: Clustered functions
+                i6pn_enabled = i6pn
 
-    if _container_app._function_def is not None:
-        if not _container_app._function_def.pty_info:
-            raise InvalidError(
-                "Interactivity is not enabled in this function. Use MODAL_INTERACTIVE_FUNCTIONS=1 to enable interactivity."
+            if info.function_name.endswith(".app"):
+                warnings.warn(
+                    "Beware: the function name is `app`. Modal will soon rename `Stub` to `App`, "
+                    "so you might run into issues if you have code like `app = modal.App()` in the same scope"
+                )
+
+            if is_generator is None:
+                is_generator = inspect.isgeneratorfunction(raw_f) or inspect.isasyncgenfunction(raw_f)
+
+            scheduler_placement: Optional[SchedulerPlacement] = _experimental_scheduler_placement
+            if region:
+                if scheduler_placement:
+                    raise InvalidError("`region` and `_experimental_scheduler_placement` cannot be used together")
+                scheduler_placement = SchedulerPlacement(region=region)
+
+            function = _Function.from_args(
+                info,
+                app=self,
+                image=image,
+                secrets=secrets,
+                schedule=schedule,
+                is_generator=is_generator,
+                gpu=gpu,
+                mounts=[*self._mounts, *mounts],
+                network_file_systems=network_file_systems,
+                allow_cross_region_volumes=allow_cross_region_volumes,
+                volumes={**self._volumes, **volumes},
+                cpu=cpu,
+                memory=memory,
+                ephemeral_disk=ephemeral_disk,
+                proxy=proxy,
+                retries=retries,
+                concurrency_limit=concurrency_limit,
+                allow_concurrent_inputs=allow_concurrent_inputs,
+                batch_max_size=batch_max_size,
+                batch_wait_ms=batch_wait_ms,
+                container_idle_timeout=container_idle_timeout,
+                timeout=timeout,
+                keep_warm=keep_warm,
+                cloud=cloud,
+                webhook_config=webhook_config,
+                enable_memory_snapshot=enable_memory_snapshot,
+                block_network=block_network,
+                max_inputs=max_inputs,
+                scheduler_placement=scheduler_placement,
+                _experimental_buffer_containers=_experimental_buffer_containers,
+                _experimental_proxy_ip=_experimental_proxy_ip,
+                i6pn_enabled=i6pn_enabled,
+                cluster_size=cluster_size,  # Experimental: Clustered functions
             )
 
-        if _container_app._function_def.concurrency_limit > 1:
-            print(
-                "Warning: Interactivity is not supported on functions with concurrency > 1. You may experience unexpected behavior."
+            self._add_function(function, webhook_config is not None)
+
+            return function
+
+        return wrapped
+
+    @typing_extensions.dataclass_transform(field_specifiers=(parameter,), kw_only_default=True)
+    def cls(
+        self,
+        _warn_parentheses_missing: Optional[bool] = None,
+        *,
+        image: Optional[_Image] = None,  # The image to run as the container for the function
+        secrets: Sequence[_Secret] = (),  # Optional Modal Secret objects with environment variables for the container
+        gpu: Union[
+            GPU_T, list[GPU_T]
+        ] = None,  # GPU request as string ("any", "T4", ...), object (`modal.GPU.A100()`, ...), or a list of either
+        serialized: bool = False,  # Whether to send the function over using cloudpickle.
+        mounts: Sequence[_Mount] = (),
+        network_file_systems: dict[
+            Union[str, PurePosixPath], _NetworkFileSystem
+        ] = {},  # Mountpoints for Modal NetworkFileSystems
+        volumes: dict[
+            Union[str, PurePosixPath], Union[_Volume, _CloudBucketMount]
+        ] = {},  # Mount points for Modal Volumes & CloudBucketMounts
+        allow_cross_region_volumes: bool = False,  # Whether using network file systems from other regions is allowed.
+        # Specify, in fractional CPU cores, how many CPU cores to request.
+        # Or, pass (request, limit) to additionally specify a hard limit in fractional CPU cores.
+        # CPU throttling will prevent a container from exceeding its specified limit.
+        cpu: Optional[Union[float, tuple[float, float]]] = None,
+        # Specify, in MiB, a memory request which is the minimum memory required.
+        # Or, pass (request, limit) to additionally specify a hard limit in MiB.
+        memory: Optional[Union[int, tuple[int, int]]] = None,
+        ephemeral_disk: Optional[int] = None,  # Specify, in MiB, the ephemeral disk size for the Function.
+        proxy: Optional[_Proxy] = None,  # Reference to a Modal Proxy to use in front of this function.
+        retries: Optional[Union[int, Retries]] = None,  # Number of times to retry each input in case of failure.
+        concurrency_limit: Optional[int] = None,  # Limit for max concurrent containers running the function.
+        allow_concurrent_inputs: Optional[int] = None,  # Number of inputs the container may fetch to run concurrently.
+        container_idle_timeout: Optional[int] = None,  # Timeout for idle containers waiting for inputs to shut down.
+        timeout: Optional[int] = None,  # Maximum execution time of the function in seconds.
+        keep_warm: Optional[int] = None,  # An optional number of containers to always keep warm.
+        cloud: Optional[str] = None,  # Cloud provider to run the function on. Possible values are aws, gcp, oci, auto.
+        region: Optional[Union[str, Sequence[str]]] = None,  # Region or regions to run the function on.
+        enable_memory_snapshot: bool = False,  # Enable memory checkpointing for faster cold starts.
+        block_network: bool = False,  # Whether to block network access
+        # Limits the number of inputs a container handles before shutting down.
+        # Use `max_inputs = 1` for single-use containers.
+        max_inputs: Optional[int] = None,
+        # Parameters below here are experimental. Use with caution!
+        _experimental_scheduler_placement: Optional[
+            SchedulerPlacement
+        ] = None,  # Experimental controls over fine-grained scheduling (alpha).
+        _experimental_buffer_containers: Optional[int] = None,  # Number of additional, idle containers to keep around.
+        _experimental_proxy_ip: Optional[str] = None,  # IP address of proxy
+        _experimental_custom_scaling_factor: Optional[float] = None,  # Custom scaling factor
+    ) -> Callable[[CLS_T], CLS_T]:
+        """
+        Decorator to register a new Modal [Cls](/docs/reference/modal.Cls) with this App.
+        """
+        if _warn_parentheses_missing:
+            raise InvalidError("Did you forget parentheses? Suggestion: `@app.cls()`.")
+
+        scheduler_placement = _experimental_scheduler_placement
+        if region:
+            if scheduler_placement:
+                raise InvalidError("`region` and `_experimental_scheduler_placement` cannot be used together")
+            scheduler_placement = SchedulerPlacement(region=region)
+
+        def wrapper(user_cls: CLS_T) -> CLS_T:
+            nonlocal keep_warm
+
+            # Check if the decorated object is a class
+            if not inspect.isclass(user_cls):
+                raise TypeError("The @app.cls decorator must be used on a class.")
+
+            batch_functions = _find_partial_methods_for_user_cls(user_cls, _PartialFunctionFlags.BATCHED)
+            if batch_functions:
+                if len(batch_functions) > 1:
+                    raise InvalidError(f"Modal class {user_cls.__name__} can only have one batched function.")
+                if len(_find_partial_methods_for_user_cls(user_cls, _PartialFunctionFlags.FUNCTION)) > 1:
+                    raise InvalidError(
+                        f"Modal class {user_cls.__name__} with a modal batched function cannot have other modal methods."  # noqa
+                    )
+                batch_function = next(iter(batch_functions.values()))
+                batch_max_size = batch_function.batch_max_size
+                batch_wait_ms = batch_function.batch_wait_ms
+            else:
+                batch_max_size = None
+                batch_wait_ms = None
+
+            if (
+                _find_partial_methods_for_user_cls(user_cls, _PartialFunctionFlags.ENTER_PRE_SNAPSHOT)
+                and not enable_memory_snapshot
+            ):
+                raise InvalidError("A class must have `enable_memory_snapshot=True` to use `snap=True` on its methods.")
+
+            info = FunctionInfo(None, serialized=serialized, user_cls=user_cls)
+
+            cls_func = _Function.from_args(
+                info,
+                app=self,
+                image=image or self._get_default_image(),
+                secrets=[*self._secrets, *secrets],
+                gpu=gpu,
+                mounts=[*self._mounts, *mounts],
+                network_file_systems=network_file_systems,
+                allow_cross_region_volumes=allow_cross_region_volumes,
+                volumes={**self._volumes, **volumes},
+                memory=memory,
+                ephemeral_disk=ephemeral_disk,
+                proxy=proxy,
+                retries=retries,
+                concurrency_limit=concurrency_limit,
+                allow_concurrent_inputs=allow_concurrent_inputs,
+                batch_max_size=batch_max_size,
+                batch_wait_ms=batch_wait_ms,
+                container_idle_timeout=container_idle_timeout,
+                timeout=timeout,
+                cpu=cpu,
+                keep_warm=keep_warm,
+                cloud=cloud,
+                enable_memory_snapshot=enable_memory_snapshot,
+                block_network=block_network,
+                max_inputs=max_inputs,
+                scheduler_placement=scheduler_placement,
+                _experimental_buffer_containers=_experimental_buffer_containers,
+                _experimental_proxy_ip=_experimental_proxy_ip,
+                _experimental_custom_scaling_factor=_experimental_custom_scaling_factor,
             )
 
-    # todo(nathan): add warning if concurrency limit > 1. but idk how to check this here
-    # todo(nathan): check if function interactivity is enabled
-    try:
-        await client.stub.FunctionStartPtyShell(Empty())
-    except Exception as e:
-        print("Error: Failed to start PTY shell.")
-        raise e
+            self._add_function(cls_func, is_web_endpoint=False)
 
+            cls: _Cls = _Cls.from_local(user_cls, self, cls_func)
 
-interact = synchronize_api(_interact)
+            tag: str = user_cls.__name__
+            self._add_class(tag, cls)
+            return cls  # type: ignore  # a _Cls instance "simulates" being the user provided class
 
+        return wrapper
 
-def is_local() -> bool:
-    """Returns if we are currently on the machine launching/deploying a Modal app
+    async def spawn_sandbox(
+        self,
+        *entrypoint_args: str,
+        image: Optional[_Image] = None,  # The image to run as the container for the sandbox.
+        mounts: Sequence[_Mount] = (),  # Mounts to attach to the sandbox.
+        secrets: Sequence[_Secret] = (),  # Environment variables to inject into the sandbox.
+        network_file_systems: dict[Union[str, PurePosixPath], _NetworkFileSystem] = {},
+        timeout: Optional[int] = None,  # Maximum execution time of the sandbox in seconds.
+        workdir: Optional[str] = None,  # Working directory of the sandbox.
+        gpu: GPU_T = None,
+        cloud: Optional[str] = None,
+        region: Optional[Union[str, Sequence[str]]] = None,  # Region or regions to run the sandbox on.
+        # Specify, in fractional CPU cores, how many CPU cores to request.
+        # Or, pass (request, limit) to additionally specify a hard limit in fractional CPU cores.
+        # CPU throttling will prevent a container from exceeding its specified limit.
+        cpu: Optional[Union[float, tuple[float, float]]] = None,
+        # Specify, in MiB, a memory request which is the minimum memory required.
+        # Or, pass (request, limit) to additionally specify a hard limit in MiB.
+        memory: Optional[Union[int, tuple[int, int]]] = None,
+        block_network: bool = False,  # Whether to block network access
+        volumes: dict[
+            Union[str, PurePosixPath], Union[_Volume, _CloudBucketMount]
+        ] = {},  # Mount points for Modal Volumes and CloudBucketMounts
+        pty_info: Optional[api_pb2.PTYInfo] = None,
+        _experimental_scheduler_placement: Optional[
+            SchedulerPlacement
+        ] = None,  # Experimental controls over fine-grained scheduling (alpha).
+    ) -> None:
+        """mdmd:hidden"""
+        arglist = ", ".join(repr(s) for s in entrypoint_args)
+        message = (
+            "`App.spawn_sandbox` is deprecated.\n\n"
+            "Sandboxes can be created using the `Sandbox` object:\n\n"
+            f"```\nsb = Sandbox.create({arglist}, app=app)\n```\n\n"
+            "See https://modal.com/docs/guide/sandbox for more info on working with sandboxes."
+        )
+        deprecation_error((2024, 7, 5), message)
 
-    Returns `True` when executed locally on the user's machine.
-    Returns `False` when executed from a Modal container in the cloud.
-    """
-    return not _is_container_app
+    def include(self, /, other_app: "_App"):
+        """Include another App's objects in this one.
 
+        Useful for splitting up Modal Apps across different self-contained files.
 
-async def _list_apps(env: str, client: Optional[_Client] = None) -> List[api_pb2.AppStats]:
-    """List apps in a given Modal environment."""
-    if client is None:
-        client = await _Client.from_env()
-    resp: api_pb2.AppListResponse = await client.stub.AppList(api_pb2.AppListRequest(environment_name=env))
-    return list(resp.apps)
+        ```python
+        app_a = modal.App("a")
+        @app.function()
+        def foo():
+            ...
+
+        app_b = modal.App("b")
+        @app.function()
+        def bar():
+            ...
+
+        app_a.include(app_b)
+
+        @app_a.local_entrypoint()
+        def main():
+            # use function declared on the included app
+            bar.remote()
+        ```
+        """
+        for tag, function in other_app._functions.items():
+            existing_function = self._functions.get(tag)
+            if existing_function and existing_function != function:
+                logger.warning(
+                    f"Named app function {tag} with existing value {existing_function} is being "
+                    f"overwritten by a different function {function}"
+                )
+
+            self._add_function(function, False)  # TODO(erikbern): webhook config?
+
+        for tag, cls in other_app._classes.items():
+            existing_cls = self._classes.get(tag)
+            if existing_cls and existing_cls != cls:
+                logger.warning(
+                    f"Named app class {tag} with existing value {existing_cls} is being "
+                    f"overwritten by a different class {cls}"
+                )
+
+            self._add_class(tag, cls)
+
+    async def _logs(self, client: Optional[_Client] = None) -> AsyncGenerator[str, None]:
+        """Stream logs from the app.
+
+        This method is considered private and its interface may change - use at your own risk!
+        """
+        if not self._app_id:
+            raise InvalidError("`app._logs` requires a running/stopped app.")
+
+        client = client or self._client or await _Client.from_env()
+
+        last_log_batch_entry_id: Optional[str] = None
+        while True:
+            request = api_pb2.AppGetLogsRequest(
+                app_id=self._app_id,
+                timeout=55,
+                last_entry_id=last_log_batch_entry_id,
+            )
+            async for log_batch in client.stub.AppGetLogs.unary_stream(request):
+                if log_batch.entry_id:
+                    # log_batch entry_id is empty for fd="server" messages from AppGetLogs
+                    last_log_batch_entry_id = log_batch.entry_id
+                if log_batch.app_done:
+                    return
+                for log in log_batch.items:
+                    if log.data:
+                        yield log.data
+
+    @classmethod
+    def _get_container_app(cls) -> Optional["_App"]:
+        """Returns the `App` running inside a container.
+
+        This will return `None` outside of a Modal container."""
+        return cls._container_app
+
+    @classmethod
+    def _reset_container_app(cls):
+        """Only used for tests."""
+        cls._container_app = None
+
+
+App = synchronize_api(_App)
+
+
+class _Stub(_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".
+    """
+
+    def __new__(cls, *args, **kwargs):
+        deprecation_warning(
+            (2024, 4, 29),
+            'The use of "Stub" has been deprecated in favor of "App".'
+            " This is a pure name change with no other implications.",
+        )
+        return _App(*args, **kwargs)
 
 
-list_apps = synchronize_api(_list_apps)
+Stub = synchronize_api(_Stub)