modal 1.0.6.dev58__py3-none-any.whl → 1.2.3.dev7__py3-none-any.whl

modal/cls.py

@@ -1,10 +1,10 @@
 # Copyright Modal Labs 2022
 import dataclasses
 import inspect
-import os
 import typing
 from collections.abc import Collection
-from typing import Any, Callable, Optional, TypeVar, Union
+from pathlib import PurePosixPath
+from typing import Any, Callable, Optional, Sequence, TypeVar, Union
 
 from google.protobuf.message import Message
 from grpclib import GRPCError, Status
@@ -12,7 +12,8 @@ from grpclib import GRPCError, Status
 from modal_proto import api_pb2
 
 from ._functions import _Function, _parse_retries
-from ._object import _Object
+from ._load_context import LoadContext
+from ._object import _Object, live_method
 from ._partial_function import (
     _find_callables_for_obj,
     _find_partial_methods_for_user_cls,
@@ -30,13 +31,13 @@ from ._utils.deprecation import (
     warn_if_passing_namespace,
     warn_on_renamed_autoscaler_settings,
 )
-from ._utils.grpc_utils import retry_transient_errors
 from ._utils.mount_utils import validate_volumes
 from .client import _Client
-from .config import config
+from .cloud_bucket_mount import _CloudBucketMount
 from .exception import ExecutionError, InvalidError, NotFoundError
 from .gpu import GPU_T
 from .retries import Retries
+from .scheduler_placement import SchedulerPlacement
 from .secret import _Secret
 from .volume import _Volume
 
@@ -80,7 +81,7 @@ def _get_class_constructor_signature(user_cls: type) -> inspect.Signature:
 @dataclasses.dataclass()
 class _ServiceOptions:
     # Note that default values should always be "untruthy" so we can detect when they are not set
-    secrets: typing.Collection[_Secret] = ()
+    secrets: Collection[_Secret] = ()
     validated_volumes: typing.Sequence[tuple[str, _Volume]] = ()
     resources: Optional[api_pb2.Resources] = None
     retry_policy: Optional[api_pb2.FunctionRetryPolicy] = None
@@ -92,6 +93,9 @@ class _ServiceOptions:
     target_concurrent_inputs: Optional[int] = None
     batch_max_size: Optional[int] = None
     batch_wait_ms: Optional[int] = None
+    scheduler_placement: Optional[api_pb2.SchedulerPlacement] = None
+    cloud: Optional[str] = None
+    cloud_bucket_mounts: typing.Sequence[tuple[str, _CloudBucketMount]] = ()
 
     def merge_options(self, new_options: "_ServiceOptions") -> "_ServiceOptions":
         """Implement protobuf-like MergeFrom semantics for this dataclass.
@@ -131,7 +135,7 @@ def _bind_instance_method(cls: "_Cls", service_function: _Function, method_name:
         method_metadata = cls._method_metadata[method_name]
         new_function._hydrate(service_function.object_id, service_function.client, method_metadata)
 
-    async def _load(fun: "_Function", resolver: Resolver, existing_object_id: Optional[str]):
+    async def _load(fun: "_Function", resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]):
         # there is currently no actual loading logic executed to create each method on
         # the *parametrized* instance of a class - it uses the parameter-bound service-function
         # for the instance. This load method just makes sure to set all attributes after the
@@ -150,11 +154,14 @@ def _bind_instance_method(cls: "_Cls", service_function: _Function, method_name:
 
     rep = f"Method({cls._name}.{method_name})"
 
+    # Bound methods should *reference* their parent Cls's LoadContext
+    # so that it can be modified in place on the parent and be reflected in the method
     fun = _Function._from_loader(
         _load,
         rep,
         deps=_deps,
         hydrate_lazily=True,
+        load_context_overrides=cls._load_context_overrides,
     )
     if service_function.is_hydrated:
         # Eager hydration (skip load) if the instance service function is already loaded
@@ -418,14 +425,13 @@ class _Obj:
 
         # Not hydrated Cls, and we don't have the class - typically a Cls.from_name that
         # has not yet been loaded. So use a special loader that loads it lazily:
-        async def method_loader(fun, resolver: Resolver, existing_object_id):
-            await resolver.load(self._cls)  # load class so we get info about methods
+        async def method_loader(fun, resolver: Resolver, load_context: LoadContext, existing_object_id):
             method_function = _get_maybe_method()
             if method_function is None:
                 raise NotFoundError(
                     f"Class has no method {k}, and attributes can't be accessed for `Cls.from_name` instances"
                 )
-            await resolver.load(method_function)  # get the appropriate method handle (lazy)
+            await resolver.load(method_function, load_context)  # get the appropriate method handle (lazy)
             fun._hydrate_from_other(method_function)
 
         # The reason we don't *always* use this lazy loader is because it precludes attribute access
@@ -433,8 +439,9 @@ class _Obj:
         return _Function._from_loader(
             method_loader,
             rep=f"Method({self._cls._name}.{k})",
-            deps=lambda: [],  # TODO: use cls as dep instead of loading inside method_loader?
+            deps=lambda: [self._cls],
             hydrate_lazily=True,
+            load_context_overrides=self._cls._load_context_overrides,
         )
 
 
@@ -481,6 +488,7 @@ class _Cls(_Object, type_prefix="cs"):
         self._callables = other._callables
         self._name = other._name
         self._method_metadata = other._method_metadata
+        self._load_context_overrides = other._load_context_overrides
 
     def _get_partial_functions(self) -> dict[str, _PartialFunction]:
         if not self._user_cls:
@@ -507,6 +515,11 @@ class _Cls(_Object, type_prefix="cs"):
         # returns method names for a *local* class only for now (used by cli)
         return self._method_partials.keys()
 
+    @live_method
+    async def _experimental_get_flash_urls(self) -> Optional[list[str]]:
+        """URL of the flash service for the class."""
+        return await self._get_class_service_function()._experimental_get_flash_urls()
+
     def _hydrate_metadata(self, metadata: Message):
         assert isinstance(metadata, api_pb2.ClassHandleMetadata)
         class_service_function = self._get_class_service_function()
@@ -568,22 +581,15 @@ More information on class parameterization can be found here: https://modal.com/
         # validate signature
         _Cls.validate_construction_mechanism(user_cls)
 
-        method_partials: dict[str, _PartialFunction] = _find_partial_methods_for_user_cls(
-            user_cls, _PartialFunctionFlags.interface_flags()
-        )
-
-        for method_name, partial_function in method_partials.items():
-            if partial_function.params.webhook_config is not None:
-                full_name = f"{user_cls.__name__}.{method_name}"
-                app._web_endpoints.append(full_name)
-            partial_function.registered = True
-
         # Disable the warning that lifecycle methods are not wrapped
-        for partial_function in _find_partial_methods_for_user_cls(
+        lifecycle_method_partials = _find_partial_methods_for_user_cls(
             user_cls, ~_PartialFunctionFlags.interface_flags()
-        ).values():
+        )
+        for partial_function in lifecycle_method_partials.values():
             partial_function.registered = True
 
+        method_partials = _find_partial_methods_for_user_cls(user_cls, _PartialFunctionFlags.interface_flags())
+
         # Get all callables
         callables: dict[str, Callable] = {
             k: pf.raw_f
@@ -594,15 +600,18 @@ More information on class parameterization can be found here: https://modal.com/
         def _deps() -> list[_Function]:
             return [class_service_function]
 
-        async def _load(self: "_Cls", resolver: Resolver, existing_object_id: Optional[str]):
+        async def _load(self: "_Cls", resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]):
             req = api_pb2.ClassCreateRequest(
-                app_id=resolver.app_id, existing_class_id=existing_object_id, only_class_function=True
+                app_id=load_context.app_id, existing_class_id=existing_object_id, only_class_function=True
             )
-            resp = await resolver.client.stub.ClassCreate(req)
-            self._hydrate(resp.class_id, resolver.client, resp.handle_metadata)
+            resp = await load_context.client.stub.ClassCreate(req)
+            self._hydrate(resp.class_id, load_context.client, resp.handle_metadata)
 
         rep = f"Cls({user_cls.__name__})"
-        cls: _Cls = _Cls._from_loader(_load, rep, deps=_deps)
+        # Pass a *reference* to the App's LoadContext - this is important since the App is
+        # the only way to infer a LoadContext for an `@app.cls`, and the App doesn't
+        # get its client until *after* the Cls is created.
+        cls: _Cls = _Cls._from_loader(_load, rep, deps=_deps, load_context_overrides=app._root_load_context)
         cls._app = app
         cls._user_cls = user_cls
         cls._class_service_function = class_service_function
@@ -619,6 +628,7 @@ More information on class parameterization can be found here: https://modal.com/
         *,
         namespace: Any = None,  # mdmd:line-hidden
         environment_name: Optional[str] = None,
+        client: Optional["_Client"] = None,
     ) -> "_Cls":
         """Reference a Cls from a deployed App by its name.
 
@@ -631,19 +641,22 @@ More information on class parameterization can be found here: https://modal.com/
         ```
         """
         warn_if_passing_namespace(namespace, "modal.Cls.from_name")
-        _environment_name = environment_name or config.get("environment")
 
-        async def _load_remote(self: _Cls, resolver: Resolver, existing_object_id: Optional[str]):
+        async def _load_remote(
+            self: _Cls, resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]
+        ):
             request = api_pb2.ClassGetRequest(
                 app_name=app_name,
                 object_tag=name,
-                environment_name=_environment_name,
+                environment_name=load_context.environment_name,
                 only_class_function=True,
             )
             try:
-                response = await retry_transient_errors(resolver.client.stub.ClassGet, request)
+                response = await load_context.client.stub.ClassGet(request)
             except NotFoundError as exc:
-                env_context = f" (in the '{environment_name}' environment)" if environment_name else ""
+                env_context = (
+                    f" (in the '{load_context.environment_name}' environment)" if load_context.environment_name else ""
+                )
                 raise NotFoundError(
                     f"Lookup failed for Cls '{name}' from the '{app_name}' app{env_context}: {exc}."
                 ) from None
@@ -654,18 +667,26 @@ More information on class parameterization can be found here: https://modal.com/
                     raise
 
             print_server_warnings(response.server_warnings)
-            await resolver.load(self._class_service_function)
-            self._hydrate(response.class_id, resolver.client, response.handle_metadata)
+            await resolver.load(self._class_service_function, load_context)
+            self._hydrate(response.class_id, load_context.client, response.handle_metadata)
+
+        environment_rep = f", environment_name={environment_name!r}" if environment_name else ""
+        rep = f"Cls.from_name({app_name!r}, {name!r}{environment_rep})"
 
-        rep = f"Cls.from_name({app_name!r}, {name!r})"
-        cls = cls._from_loader(_load_remote, rep, is_another_app=True, hydrate_lazily=True)
+        load_context_overrides = LoadContext(client=client, environment_name=environment_name)
+        cls = cls._from_loader(
+            _load_remote,
+            rep,
+            is_another_app=True,
+            hydrate_lazily=True,
+            load_context_overrides=load_context_overrides,
+        )
 
         class_service_name = f"{name}.*"  # special name of the base service function for the class
         cls._class_service_function = _Function._from_name(
             app_name,
             class_service_name,
-            namespace=namespace,
-            environment_name=_environment_name,
+            load_context_overrides=load_context_overrides,
         )
         cls._name = name
         return cls
@@ -677,13 +698,16 @@ More information on class parameterization can be found here: https://modal.com/
         cpu: Optional[Union[float, tuple[float, float]]] = None,
         memory: Optional[Union[int, tuple[int, int]]] = None,
         gpu: GPU_T = None,
-        secrets: Collection[_Secret] = (),
-        volumes: dict[Union[str, os.PathLike], _Volume] = {},
+        env: Optional[dict[str, Optional[str]]] = None,
+        secrets: Optional[Collection[_Secret]] = None,
+        volumes: dict[Union[str, PurePosixPath], Union[_Volume, _CloudBucketMount]] = {},
         retries: Optional[Union[int, Retries]] = None,
         max_containers: Optional[int] = None,  # Limit on the number of containers that can be concurrently running.
         buffer_containers: Optional[int] = None,  # Additional containers to scale up while Function is active.
         scaledown_window: Optional[int] = None,  # Max amount of time a container can remain idle before scaling down.
         timeout: Optional[int] = None,
+        region: Optional[Union[str, Sequence[str]]] = None,  # Region or regions to run the function on.
+        cloud: Optional[str] = None,  # Cloud provider to run the function on. Possible values are aws, gcp, oci, auto.
         # The following parameters are deprecated
         concurrency_limit: Optional[int] = None,  # Now called `max_containers`
         container_idle_timeout: Optional[int] = None,  # Now called `scaledown_window`
@@ -722,6 +746,8 @@ More information on class parameterization can be found here: https://modal.com/
         else:
             resources = None
 
+        scheduler_placement = SchedulerPlacement(region=region).proto if region else None
+
         if allow_concurrent_inputs is not None:
             deprecation_warning(
                 (2025, 5, 9),
@@ -729,7 +755,7 @@ More information on class parameterization can be found here: https://modal.com/
                 " please use the `.with_concurrency` method instead.",
             )
 
-        async def _load_from_base(new_cls, resolver, existing_object_id):
+        async def _load_from_base(new_cls, resolver, load_context, existing_object_id):
             # this is a bit confusing, the cls will always have the same metadata
             # since it has the same *class* service function (i.e. "template")
             # But the (instance) service function for each Obj will be different
@@ -738,25 +764,44 @@ More information on class parameterization can be found here: https://modal.com/
             if not self.is_hydrated:
                 # this should only happen for Cls.from_name instances
                 # other classes should already be hydrated!
-                await resolver.load(self)
+                await resolver.load(self, load_context)
 
             new_cls._initialize_from_other(self)
 
         def _deps():
             return []
 
-        cls = _Cls._from_loader(_load_from_base, rep=f"{self._name}.with_options(...)", is_another_app=True, deps=_deps)
+        cls = _Cls._from_loader(
+            _load_from_base,
+            rep=f"{self._name}.with_options(...)",
+            is_another_app=True,
+            deps=_deps,
+            load_context_overrides=self._load_context_overrides,
+            hydrate_lazily=True,
+        )
         cls._initialize_from_other(self)
 
+        # Validate volumes
+        validated_volumes = validate_volumes(volumes)
+        cloud_bucket_mounts = [(k, v) for k, v in validated_volumes if isinstance(v, _CloudBucketMount)]
+        validated_volumes_no_cloud_buckets = [(k, v) for k, v in validated_volumes if isinstance(v, _Volume)]
+
+        secrets = secrets or []
+        if env:
+            secrets = [*secrets, _Secret.from_dict(env)]
+
         new_options = _ServiceOptions(
             secrets=secrets,
-            validated_volumes=validate_volumes(volumes),
+            validated_volumes=validated_volumes_no_cloud_buckets,
+            cloud_bucket_mounts=cloud_bucket_mounts,
             resources=resources,
             retry_policy=retry_policy,
             max_containers=max_containers,
             buffer_containers=buffer_containers,
             scaledown_window=scaledown_window,
             timeout_secs=timeout,
+            scheduler_placement=scheduler_placement,
+            cloud=cloud,
             # Note: set both for backwards / forwards compatibility
             # But going forward `.with_concurrency` is the preferred method with distinct parameterization
             max_concurrent_inputs=allow_concurrent_inputs,
@@ -778,16 +823,21 @@ More information on class parameterization can be found here: https://modal.com/
         ```
         """
 
-        async def _load_from_base(new_cls, resolver, existing_object_id):
+        async def _load_from_base(new_cls, resolver, load_context, existing_object_id):
             if not self.is_hydrated:
-                await resolver.load(self)
+                await resolver.load(self, load_context)
             new_cls._initialize_from_other(self)
 
         def _deps():
             return []
 
         cls = _Cls._from_loader(
-            _load_from_base, rep=f"{self._name}.with_concurrency(...)", is_another_app=True, deps=_deps
+            _load_from_base,
+            rep=f"{self._name}.with_concurrency(...)",
+            is_another_app=True,
+            deps=_deps,
+            load_context_overrides=self._load_context_overrides,
+            hydrate_lazily=True,
         )
         cls._initialize_from_other(self)
 
@@ -807,16 +857,21 @@ More information on class parameterization can be found here: https://modal.com/
         ```
         """
 
-        async def _load_from_base(new_cls, resolver, existing_object_id):
+        async def _load_from_base(new_cls, resolver, load_context, existing_object_id):
             if not self.is_hydrated:
-                await resolver.load(self)
+                await resolver.load(self, load_context)
             new_cls._initialize_from_other(self)
 
         def _deps():
             return []
 
         cls = _Cls._from_loader(
-            _load_from_base, rep=f"{self._name}.with_concurrency(...)", is_another_app=True, deps=_deps
+            _load_from_base,
+            rep=f"{self._name}.with_concurrency(...)",
+            is_another_app=True,
+            deps=_deps,
+            load_context_overrides=self._load_context_overrides,
+            hydrate_lazily=True,
         )
         cls._initialize_from_other(self)
 
@@ -824,46 +879,6 @@ More information on class parameterization can be found here: https://modal.com/
         cls._options.merge_options(batching_options)
         return cls
 
-    @staticmethod
-    async def lookup(
-        app_name: str,
-        name: str,
-        namespace=None,  # mdmd:line-hidden
-        client: Optional[_Client] = None,
-        environment_name: Optional[str] = None,
-    ) -> "_Cls":
-        """mdmd:hidden
-        Lookup a Cls from a deployed App by its name.
-
-        DEPRECATED: This method is deprecated in favor of `modal.Cls.from_name`.
-
-        In contrast to `modal.Cls.from_name`, this is an eager method
-        that will hydrate the local object with metadata from Modal servers.
-
-        ```python notest
-        Model = modal.Cls.from_name("other-app", "Model")
-        model = Model()
-        model.inference(...)
-        ```
-        """
-        deprecation_warning(
-            (2025, 1, 27),
-            "`modal.Cls.lookup` is deprecated and will be removed in a future release."
-            " It can be replaced with `modal.Cls.from_name`."
-            "\n\nSee https://modal.com/docs/guide/modal-1-0-migration for more information.",
-        )
-        warn_if_passing_namespace(namespace, "modal.Cls.lookup")
-        obj = _Cls.from_name(
-            app_name,
-            name,
-            environment_name=environment_name,
-        )
-        if client is None:
-            client = await _Client.from_env()
-        resolver = Resolver(client=client)
-        await resolver.load(obj)
-        return obj
-
     @synchronizer.no_input_translation
     def __call__(self, *args, **kwargs) -> _Obj:
         """This acts as the class constructor."""
@@ -876,18 +891,31 @@ More information on class parameterization can be found here: https://modal.com/
         )
 
     def __getattr__(self, k):
-        # TODO: remove this method - access to attributes on classes (not instances) should be discouraged
-        if not self._is_local() or k in self._method_partials:
-            # if not local (== k *could* be a method) or it is local and we know k is a method
-            deprecation_warning(
-                (2025, 1, 13),
-                "Calling a method on an uninstantiated class will soon be deprecated; "
-                "update your code to instantiate the class first, i.e.:\n"
-                f"{self._name}().{k} instead of {self._name}.{k}",
+        if self._user_cls is not None:
+            # local class, we can check if there are static attributes and let the user access them
+            # except if they are PartialFunction (i.e. methods)
+            v = getattr(self._user_cls, k)
+            if not isinstance(v, modal.partial_function.PartialFunction):
+                return v
+
+        # We create a synthetic dummy Function that is guaranteed to raise an AttributeError when
+        # a user tries to use any of its "live methods" - this lets us raise exceptions for users
+        # only if they try to access methods on a Cls as if they were methods on the instance.
+        async def error_loader(
+            fun: _Function, resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]
+        ):
+            raise AttributeError(
+                "You can't access methods on a Cls directly - Did you forget to instantiate the class first?\n"
+                "e.g. instead of MyClass.method.remote(), do MyClass().method.remote()"
             )
-            return getattr(self(), k)
-        # non-method attribute access on local class - arguably shouldn't be used either:
-        return getattr(self._user_cls, k)
+
+        return _Function._from_loader(
+            error_loader,
+            rep=f"UnboundMethod({self._name}.{k})",
+            deps=lambda: [],
+            hydrate_lazily=True,
+            load_context_overrides=self._load_context_overrides,
+        )
 
     def _is_local(self) -> bool:
         return self._user_cls is not None