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

modal/dict.pyi

@@ -1,195 +1,200 @@
+import collections.abc
 import modal.client
 import modal.object
 import synchronicity.combined_types
 import typing
 import typing_extensions
 
-def _serialize_dict(data):
-    ...
-
+def _serialize_dict(data): ...
 
 class _Dict(modal.object._Object):
-    @staticmethod
-    def new(data: typing.Union[dict, None] = None) -> _Dict:
-        ...
-
-    def __init__(self, data={}):
-        ...
-
+    def __init__(self, data={}): ...
     @classmethod
-    def ephemeral(cls: typing.Type[_Dict], data: typing.Union[dict, None] = None, client: typing.Union[modal.client._Client, None] = None, environment_name: typing.Union[str, None] = None, _heartbeat_sleep: float = 300) -> typing.AsyncContextManager[_Dict]:
-        ...
-
+    def ephemeral(
+        cls: type[_Dict],
+        data: typing.Optional[dict] = None,
+        client: typing.Optional[modal.client._Client] = None,
+        environment_name: typing.Optional[str] = None,
+        _heartbeat_sleep: float = 300,
+    ) -> typing.AsyncContextManager[_Dict]: ...
     @staticmethod
-    def from_name(label: str, data: typing.Union[dict, None] = None, namespace=1, environment_name: typing.Union[str, None] = None, create_if_missing: bool = False) -> _Dict:
-        ...
-
+    def from_name(
+        name: str,
+        data: typing.Optional[dict] = None,
+        namespace=1,
+        environment_name: typing.Optional[str] = None,
+        create_if_missing: bool = False,
+    ) -> _Dict: ...
     @staticmethod
-    def persisted(label: str, namespace=1, environment_name: typing.Union[str, None] = None) -> _Dict:
-        ...
-
+    async def lookup(
+        name: str,
+        data: typing.Optional[dict] = None,
+        namespace=1,
+        client: typing.Optional[modal.client._Client] = None,
+        environment_name: typing.Optional[str] = None,
+        create_if_missing: bool = False,
+    ) -> _Dict: ...
     @staticmethod
-    async def lookup(label: str, data: typing.Union[dict, None] = None, namespace=1, client: typing.Union[modal.client._Client, None] = None, environment_name: typing.Union[str, None] = None, create_if_missing: bool = False) -> _Dict:
-        ...
-
-    async def clear(self) -> None:
-        ...
-
-    async def get(self, key: typing.Any, default: typing.Union[typing.Any, None] = None) -> typing.Any:
-        ...
-
-    async def contains(self, key: typing.Any) -> bool:
-        ...
-
-    async def len(self) -> int:
-        ...
-
-    async def __getitem__(self, key: typing.Any) -> typing.Any:
-        ...
-
-    async def update(self, **kwargs) -> None:
-        ...
-
-    async def put(self, key: typing.Any, value: typing.Any) -> None:
-        ...
-
-    async def __setitem__(self, key: typing.Any, value: typing.Any) -> None:
-        ...
-
-    async def pop(self, key: typing.Any) -> typing.Any:
-        ...
-
-    async def __delitem__(self, key: typing.Any) -> typing.Any:
-        ...
-
-    async def __contains__(self, key: typing.Any) -> bool:
-        ...
-
+    async def delete(
+        name: str,
+        *,
+        client: typing.Optional[modal.client._Client] = None,
+        environment_name: typing.Optional[str] = None,
+    ): ...
+    async def clear(self) -> None: ...
+    async def get(self, key: typing.Any, default: typing.Optional[typing.Any] = None) -> typing.Any: ...
+    async def contains(self, key: typing.Any) -> bool: ...
+    async def len(self) -> int: ...
+    async def __getitem__(self, key: typing.Any) -> typing.Any: ...
+    async def update(self, **kwargs) -> None: ...
+    async def put(self, key: typing.Any, value: typing.Any) -> None: ...
+    async def __setitem__(self, key: typing.Any, value: typing.Any) -> None: ...
+    async def pop(self, key: typing.Any) -> typing.Any: ...
+    async def __delitem__(self, key: typing.Any) -> typing.Any: ...
+    async def __contains__(self, key: typing.Any) -> bool: ...
+    def keys(self) -> collections.abc.AsyncIterator[typing.Any]: ...
+    def values(self) -> collections.abc.AsyncIterator[typing.Any]: ...
+    def items(self) -> collections.abc.AsyncIterator[tuple[typing.Any, typing.Any]]: ...
 
 class Dict(modal.object.Object):
-    def __init__(self, data={}):
-        ...
-
-    @staticmethod
-    def new(data: typing.Union[dict, None] = None) -> Dict:
-        ...
-
+    def __init__(self, data={}): ...
     @classmethod
-    def ephemeral(cls: typing.Type[Dict], data: typing.Union[dict, None] = None, client: typing.Union[modal.client.Client, None] = None, environment_name: typing.Union[str, None] = None, _heartbeat_sleep: float = 300) -> synchronicity.combined_types.AsyncAndBlockingContextManager[Dict]:
-        ...
-
-    @staticmethod
-    def from_name(label: str, data: typing.Union[dict, None] = None, namespace=1, environment_name: typing.Union[str, None] = None, create_if_missing: bool = False) -> Dict:
-        ...
-
+    def ephemeral(
+        cls: type[Dict],
+        data: typing.Optional[dict] = None,
+        client: typing.Optional[modal.client.Client] = None,
+        environment_name: typing.Optional[str] = None,
+        _heartbeat_sleep: float = 300,
+    ) -> synchronicity.combined_types.AsyncAndBlockingContextManager[Dict]: ...
     @staticmethod
-    def persisted(label: str, namespace=1, environment_name: typing.Union[str, None] = None) -> Dict:
-        ...
+    def from_name(
+        name: str,
+        data: typing.Optional[dict] = None,
+        namespace=1,
+        environment_name: typing.Optional[str] = None,
+        create_if_missing: bool = False,
+    ) -> Dict: ...
 
     class __lookup_spec(typing_extensions.Protocol):
-        def __call__(self, label: str, data: typing.Union[dict, None] = None, namespace=1, client: typing.Union[modal.client.Client, None] = None, environment_name: typing.Union[str, None] = None, create_if_missing: bool = False) -> Dict:
-            ...
-
-        async def aio(self, *args, **kwargs) -> Dict:
-            ...
+        def __call__(
+            self,
+            name: str,
+            data: typing.Optional[dict] = None,
+            namespace=1,
+            client: typing.Optional[modal.client.Client] = None,
+            environment_name: typing.Optional[str] = None,
+            create_if_missing: bool = False,
+        ) -> Dict: ...
+        async def aio(
+            self,
+            name: str,
+            data: typing.Optional[dict] = None,
+            namespace=1,
+            client: typing.Optional[modal.client.Client] = None,
+            environment_name: typing.Optional[str] = None,
+            create_if_missing: bool = False,
+        ) -> Dict: ...
 
     lookup: __lookup_spec
 
-    class __clear_spec(typing_extensions.Protocol):
-        def __call__(self) -> None:
-            ...
+    class __delete_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            name: str,
+            *,
+            client: typing.Optional[modal.client.Client] = None,
+            environment_name: typing.Optional[str] = None,
+        ): ...
+        async def aio(
+            self,
+            name: str,
+            *,
+            client: typing.Optional[modal.client.Client] = None,
+            environment_name: typing.Optional[str] = None,
+        ): ...
+
+    delete: __delete_spec
 
-        async def aio(self, *args, **kwargs) -> None:
-            ...
+    class __clear_spec(typing_extensions.Protocol):
+        def __call__(self) -> None: ...
+        async def aio(self) -> None: ...
 
     clear: __clear_spec
 
     class __get_spec(typing_extensions.Protocol):
-        def __call__(self, key: typing.Any, default: typing.Union[typing.Any, None] = None) -> typing.Any:
-            ...
-
-        async def aio(self, *args, **kwargs) -> typing.Any:
-            ...
+        def __call__(self, key: typing.Any, default: typing.Optional[typing.Any] = None) -> typing.Any: ...
+        async def aio(self, key: typing.Any, default: typing.Optional[typing.Any] = None) -> typing.Any: ...
 
     get: __get_spec
 
     class __contains_spec(typing_extensions.Protocol):
-        def __call__(self, key: typing.Any) -> bool:
-            ...
-
-        async def aio(self, *args, **kwargs) -> bool:
-            ...
+        def __call__(self, key: typing.Any) -> bool: ...
+        async def aio(self, key: typing.Any) -> bool: ...
 
     contains: __contains_spec
 
     class __len_spec(typing_extensions.Protocol):
-        def __call__(self) -> int:
-            ...
-
-        async def aio(self, *args, **kwargs) -> int:
-            ...
+        def __call__(self) -> int: ...
+        async def aio(self) -> int: ...
 
     len: __len_spec
 
     class ____getitem___spec(typing_extensions.Protocol):
-        def __call__(self, key: typing.Any) -> typing.Any:
-            ...
-
-        async def aio(self, *args, **kwargs) -> typing.Any:
-            ...
+        def __call__(self, key: typing.Any) -> typing.Any: ...
+        async def aio(self, key: typing.Any) -> typing.Any: ...
 
     __getitem__: ____getitem___spec
 
     class __update_spec(typing_extensions.Protocol):
-        def __call__(self, **kwargs) -> None:
-            ...
-
-        async def aio(self, *args, **kwargs) -> None:
-            ...
+        def __call__(self, **kwargs) -> None: ...
+        async def aio(self, **kwargs) -> None: ...
 
     update: __update_spec
 
     class __put_spec(typing_extensions.Protocol):
-        def __call__(self, key: typing.Any, value: typing.Any) -> None:
-            ...
-
-        async def aio(self, *args, **kwargs) -> None:
-            ...
+        def __call__(self, key: typing.Any, value: typing.Any) -> None: ...
+        async def aio(self, key: typing.Any, value: typing.Any) -> None: ...
 
     put: __put_spec
 
     class ____setitem___spec(typing_extensions.Protocol):
-        def __call__(self, key: typing.Any, value: typing.Any) -> None:
-            ...
-
-        async def aio(self, *args, **kwargs) -> None:
-            ...
+        def __call__(self, key: typing.Any, value: typing.Any) -> None: ...
+        async def aio(self, key: typing.Any, value: typing.Any) -> None: ...
 
     __setitem__: ____setitem___spec
 
     class __pop_spec(typing_extensions.Protocol):
-        def __call__(self, key: typing.Any) -> typing.Any:
-            ...
-
-        async def aio(self, *args, **kwargs) -> typing.Any:
-            ...
+        def __call__(self, key: typing.Any) -> typing.Any: ...
+        async def aio(self, key: typing.Any) -> typing.Any: ...
 
     pop: __pop_spec
 
     class ____delitem___spec(typing_extensions.Protocol):
-        def __call__(self, key: typing.Any) -> typing.Any:
-            ...
-
-        async def aio(self, *args, **kwargs) -> typing.Any:
-            ...
+        def __call__(self, key: typing.Any) -> typing.Any: ...
+        async def aio(self, key: typing.Any) -> typing.Any: ...
 
     __delitem__: ____delitem___spec
 
     class ____contains___spec(typing_extensions.Protocol):
-        def __call__(self, key: typing.Any) -> bool:
-            ...
-
-        async def aio(self, *args, **kwargs) -> bool:
-            ...
+        def __call__(self, key: typing.Any) -> bool: ...
+        async def aio(self, key: typing.Any) -> bool: ...
 
     __contains__: ____contains___spec
+
+    class __keys_spec(typing_extensions.Protocol):
+        def __call__(self) -> typing.Iterator[typing.Any]: ...
+        def aio(self) -> collections.abc.AsyncIterator[typing.Any]: ...
+
+    keys: __keys_spec
+
+    class __values_spec(typing_extensions.Protocol):
+        def __call__(self) -> typing.Iterator[typing.Any]: ...
+        def aio(self) -> collections.abc.AsyncIterator[typing.Any]: ...
+
+    values: __values_spec
+
+    class __items_spec(typing_extensions.Protocol):
+        def __call__(self) -> typing.Iterator[tuple[typing.Any, typing.Any]]: ...
+        def aio(self) -> collections.abc.AsyncIterator[tuple[typing.Any, typing.Any]]: ...
+
+    items: __items_spec

modal/environments.py

@@ -1,14 +1,115 @@
 # Copyright Modal Labs 2023
-from typing import List, Optional
+from dataclasses import dataclass
+from typing import Optional
 
 from google.protobuf.empty_pb2 import Empty
+from google.protobuf.message import Message
 from google.protobuf.wrappers_pb2 import StringValue
 
-from modal.client import _Client
-from modal.config import config
 from modal_proto import api_pb2
 
-from ._utils.async_utils import synchronizer
+from ._resolver import Resolver
+from ._utils.async_utils import synchronize_api, synchronizer
+from ._utils.deprecation import renamed_parameter
+from ._utils.grpc_utils import retry_transient_errors
+from ._utils.name_utils import check_object_name
+from .client import _Client
+from .config import config, logger
+from .object import _Object
+
+
+@dataclass(frozen=True)
+class EnvironmentSettings:
+    image_builder_version: str  # Ideally would be typed with ImageBuilderVersion literal
+    webhook_suffix: str
+
+
+class _Environment(_Object, type_prefix="en"):
+    _settings: EnvironmentSettings
+
+    def __init__(self):
+        """mdmd:hidden"""
+        raise RuntimeError(
+            "`Environment(...)` constructor is not allowed."
+            " Please use `Environment.from_name` or `Environment.lookup` instead."
+        )
+
+    # TODO(michael) Keeping this private for now until we decide what else should be in it
+    # And what the rules should be about updates / mutability
+    # @property
+    # def settings(self) -> EnvironmentSettings:
+    #     return self._settings
+
+    def _hydrate_metadata(self, metadata: Message):
+        # Overridden concrete implementation of base class method
+        assert metadata and isinstance(metadata, api_pb2.EnvironmentMetadata)
+        # TODO(michael) should probably expose the `name` from the metadata
+        # as the way to discover the name of the "default" environment
+
+        # Is there a simpler way to go Message -> Dataclass?
+        self._settings = EnvironmentSettings(
+            image_builder_version=metadata.settings.image_builder_version,
+            webhook_suffix=metadata.settings.webhook_suffix,
+        )
+
+    @staticmethod
+    @renamed_parameter((2024, 12, 18), "label", "name")
+    async def from_name(
+        name: str,
+        create_if_missing: bool = False,
+    ):
+        if name:
+            # Allow null names for the case where we want to look up the "default" environment,
+            # which is defined by the server. It feels messy to have "from_name" without a name, though?
+            # We're adding this mostly for internal use right now. We could consider an environment-only
+            # alternate constructor, like `Environment.get_default`, rather than exposing "unnamed"
+            # environments as part of public API when we make this class more useful.
+            check_object_name(name, "Environment")
+
+        async def _load(self: _Environment, resolver: Resolver, existing_object_id: Optional[str]):
+            request = api_pb2.EnvironmentGetOrCreateRequest(
+                deployment_name=name,
+                object_creation_type=(
+                    api_pb2.OBJECT_CREATION_TYPE_CREATE_IF_MISSING
+                    if create_if_missing
+                    else api_pb2.OBJECT_CREATION_TYPE_UNSPECIFIED
+                ),
+            )
+            response = await retry_transient_errors(resolver.client.stub.EnvironmentGetOrCreate, request)
+            logger.debug(f"Created environment with id {response.environment_id}")
+            self._hydrate(response.environment_id, resolver.client, response.metadata)
+
+        # TODO environment name (and id?) in the repr? (We should make reprs consistently more useful)
+        return _Environment._from_loader(_load, "Environment()", is_another_app=True, hydrate_lazily=True)
+
+    @staticmethod
+    @renamed_parameter((2024, 12, 18), "label", "name")
+    async def lookup(
+        name: str,
+        client: Optional[_Client] = None,
+        create_if_missing: bool = False,
+    ):
+        obj = await _Environment.from_name(name, create_if_missing=create_if_missing)
+        if client is None:
+            client = await _Client.from_env()
+        resolver = Resolver(client=client)
+        await resolver.load(obj)
+        return obj
+
+
+Environment = synchronize_api(_Environment)
+
+
+# Needs to be after definition; synchronicity interferes with forward references?
+ENVIRONMENT_CACHE: dict[str, _Environment] = {}
+
+
+async def _get_environment_cached(name: str, client: _Client) -> _Environment:
+    if name in ENVIRONMENT_CACHE:
+        return ENVIRONMENT_CACHE[name]
+    environment = await _Environment.lookup(name, client)
+    ENVIRONMENT_CACHE[name] = environment
+    return environment
 
 
 @synchronizer.create_blocking
@@ -53,7 +154,7 @@ async def create_environment(name: str, client: Optional[_Client] = None):
 
 
 @synchronizer.create_blocking
-async def list_environments(client: Optional[_Client] = None) -> List[api_pb2.EnvironmentListItem]:
+async def list_environments(client: Optional[_Client] = None) -> list[api_pb2.EnvironmentListItem]:
     if client is None:
         client = await _Client.from_env()
     resp = await client.stub.EnvironmentList(Empty())

modal/environments.pyi

@@ -1,47 +1,99 @@
+import google.protobuf.message
 import modal.client
+import modal.object
 import modal_proto.api_pb2
 import typing
 import typing_extensions
 
-class __delete_environment_spec(typing_extensions.Protocol):
-    def __call__(self, name: str, client: typing.Union[modal.client.Client, None] = None):
-        ...
+class EnvironmentSettings:
+    image_builder_version: str
+    webhook_suffix: str
 
-    async def aio(self, *args, **kwargs):
-        ...
+    def __init__(self, image_builder_version: str, webhook_suffix: str) -> None: ...
+    def __repr__(self): ...
+    def __eq__(self, other): ...
+    def __setattr__(self, name, value): ...
+    def __delattr__(self, name): ...
+    def __hash__(self): ...
 
-delete_environment: __delete_environment_spec
+class _Environment(modal.object._Object):
+    _settings: EnvironmentSettings
 
+    def __init__(self): ...
+    def _hydrate_metadata(self, metadata: google.protobuf.message.Message): ...
+    @staticmethod
+    async def from_name(name: str, create_if_missing: bool = False): ...
+    @staticmethod
+    async def lookup(
+        name: str, client: typing.Optional[modal.client._Client] = None, create_if_missing: bool = False
+    ): ...
 
-class __update_environment_spec(typing_extensions.Protocol):
-    def __call__(self, current_name: str, *, new_name: typing.Union[str, None] = None, new_web_suffix: typing.Union[str, None] = None, client: typing.Union[modal.client.Client, None] = None):
-        ...
+class Environment(modal.object.Object):
+    _settings: EnvironmentSettings
 
-    async def aio(self, *args, **kwargs):
-        ...
+    def __init__(self): ...
+    def _hydrate_metadata(self, metadata: google.protobuf.message.Message): ...
 
-update_environment: __update_environment_spec
+    class __from_name_spec(typing_extensions.Protocol):
+        def __call__(self, name: str, create_if_missing: bool = False): ...
+        async def aio(self, name: str, create_if_missing: bool = False): ...
 
+    from_name: __from_name_spec
 
-class __create_environment_spec(typing_extensions.Protocol):
-    def __call__(self, name: str, client: typing.Union[modal.client.Client, None] = None):
-        ...
+    class __lookup_spec(typing_extensions.Protocol):
+        def __call__(
+            self, name: str, client: typing.Optional[modal.client.Client] = None, create_if_missing: bool = False
+        ): ...
+        async def aio(
+            self, name: str, client: typing.Optional[modal.client.Client] = None, create_if_missing: bool = False
+        ): ...
 
-    async def aio(self, *args, **kwargs):
-        ...
+    lookup: __lookup_spec
 
-create_environment: __create_environment_spec
+async def _get_environment_cached(name: str, client: modal.client._Client) -> _Environment: ...
 
+class __delete_environment_spec(typing_extensions.Protocol):
+    def __call__(self, name: str, client: typing.Optional[modal.client.Client] = None): ...
+    async def aio(self, name: str, client: typing.Optional[modal.client.Client] = None): ...
 
-class __list_environments_spec(typing_extensions.Protocol):
-    def __call__(self, client: typing.Union[modal.client.Client, None] = None) -> typing.List[modal_proto.api_pb2.EnvironmentListItem]:
-        ...
+delete_environment: __delete_environment_spec
 
-    async def aio(self, *args, **kwargs) -> typing.List[modal_proto.api_pb2.EnvironmentListItem]:
-        ...
+class __update_environment_spec(typing_extensions.Protocol):
+    def __call__(
+        self,
+        current_name: str,
+        *,
+        new_name: typing.Optional[str] = None,
+        new_web_suffix: typing.Optional[str] = None,
+        client: typing.Optional[modal.client.Client] = None,
+    ): ...
+    async def aio(
+        self,
+        current_name: str,
+        *,
+        new_name: typing.Optional[str] = None,
+        new_web_suffix: typing.Optional[str] = None,
+        client: typing.Optional[modal.client.Client] = None,
+    ): ...
+
+update_environment: __update_environment_spec
+
+class __create_environment_spec(typing_extensions.Protocol):
+    def __call__(self, name: str, client: typing.Optional[modal.client.Client] = None): ...
+    async def aio(self, name: str, client: typing.Optional[modal.client.Client] = None): ...
+
+create_environment: __create_environment_spec
+
+class __list_environments_spec(typing_extensions.Protocol):
+    def __call__(
+        self, client: typing.Optional[modal.client.Client] = None
+    ) -> list[modal_proto.api_pb2.EnvironmentListItem]: ...
+    async def aio(
+        self, client: typing.Optional[modal.client.Client] = None
+    ) -> list[modal_proto.api_pb2.EnvironmentListItem]: ...
 
 list_environments: __list_environments_spec
 
+def ensure_env(environment_name: typing.Optional[str] = None) -> str: ...
 
-def ensure_env(environment_name: typing.Union[str, None] = None) -> str:
-    ...
+ENVIRONMENT_CACHE: dict[str, _Environment]