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

modal/dict.pyi

@@ -1,13 +1,365 @@
 import collections.abc
+import datetime
+import google.protobuf.message
 import modal._object
 import modal.client
 import modal.object
+import modal_proto.api_pb2
+import synchronicity
 import synchronicity.combined_types
 import typing
 import typing_extensions
 
+class _NoDefaultSentinel:
+    def __repr__(self) -> str:
+        """Return repr(self)."""
+        ...
+
+_NO_DEFAULT: _NoDefaultSentinel
+
 def _serialize_dict(data): ...
 
+class DictInfo:
+    """Information about a Dict object."""
+
+    name: typing.Optional[str]
+    created_at: datetime.datetime
+    created_by: typing.Optional[str]
+
+    def __init__(
+        self, name: typing.Optional[str], created_at: datetime.datetime, created_by: typing.Optional[str]
+    ) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    def __repr__(self):
+        """Return repr(self)."""
+        ...
+
+    def __eq__(self, other):
+        """Return self==value."""
+        ...
+
+class _DictManager:
+    """Namespace with methods for managing named Dict objects."""
+    @staticmethod
+    async def create(
+        name: str,
+        *,
+        allow_existing: bool = False,
+        environment_name: typing.Optional[str] = None,
+        client: typing.Optional[modal.client._Client] = None,
+    ) -> None:
+        """Create a new Dict object.
+
+        **Examples:**
+
+        ```python notest
+        modal.Dict.objects.create("my-dict")
+        ```
+
+        Dicts will be created in the active environment, or another one can be specified:
+
+        ```python notest
+        modal.Dict.objects.create("my-dict", environment_name="dev")
+        ```
+
+        By default, an error will be raised if the Dict already exists, but passing
+        `allow_existing=True` will make the creation attempt a no-op in this case.
+
+        ```python notest
+        modal.Dict.objects.create("my-dict", allow_existing=True)
+        ```
+
+        Note that this method does not return a local instance of the Dict. You can use
+        `modal.Dict.from_name` to perform a lookup after creation.
+
+        Added in v1.1.2.
+        """
+        ...
+
+    @staticmethod
+    async def list(
+        *,
+        max_objects: typing.Optional[int] = None,
+        created_before: typing.Union[datetime.datetime, str, None] = None,
+        environment_name: str = "",
+        client: typing.Optional[modal.client._Client] = None,
+    ) -> list[_Dict]:
+        """Return a list of hydrated Dict objects.
+
+        **Examples:**
+
+        ```python
+        dicts = modal.Dict.objects.list()
+        print([d.name for d in dicts])
+        ```
+
+        Dicts will be retreived from the active environment, or another one can be specified:
+
+        ```python notest
+        dev_dicts = modal.Dict.objects.list(environment_name="dev")
+        ```
+
+        By default, all named Dict are returned, newest to oldest. It's also possible to limit the
+        number of results and to filter by creation date:
+
+        ```python
+        dicts = modal.Dict.objects.list(max_objects=10, created_before="2025-01-01")
+        ```
+
+        Added in v1.1.2.
+        """
+        ...
+
+    @staticmethod
+    async def delete(
+        name: str,
+        *,
+        allow_missing: bool = False,
+        environment_name: typing.Optional[str] = None,
+        client: typing.Optional[modal.client._Client] = None,
+    ):
+        """Delete a named Dict.
+
+        Warning: This deletes an *entire Dict*, not just a specific key.
+        Deletion is irreversible and will affect any Apps currently using the Dict.
+
+        **Examples:**
+
+        ```python notest
+        await modal.Dict.objects.delete("my-dict")
+        ```
+
+        Dicts will be deleted from the active environment, or another one can be specified:
+
+        ```python notest
+        await modal.Dict.objects.delete("my-dict", environment_name="dev")
+        ```
+
+        Added in v1.1.2.
+        """
+        ...
+
+class DictManager:
+    """Namespace with methods for managing named Dict objects."""
+    def __init__(self, /, *args, **kwargs):
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    class __create_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            name: str,
+            *,
+            allow_existing: bool = False,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> None:
+            """Create a new Dict object.
+
+            **Examples:**
+
+            ```python notest
+            modal.Dict.objects.create("my-dict")
+            ```
+
+            Dicts will be created in the active environment, or another one can be specified:
+
+            ```python notest
+            modal.Dict.objects.create("my-dict", environment_name="dev")
+            ```
+
+            By default, an error will be raised if the Dict already exists, but passing
+            `allow_existing=True` will make the creation attempt a no-op in this case.
+
+            ```python notest
+            modal.Dict.objects.create("my-dict", allow_existing=True)
+            ```
+
+            Note that this method does not return a local instance of the Dict. You can use
+            `modal.Dict.from_name` to perform a lookup after creation.
+
+            Added in v1.1.2.
+            """
+            ...
+
+        async def aio(
+            self,
+            /,
+            name: str,
+            *,
+            allow_existing: bool = False,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> None:
+            """Create a new Dict object.
+
+            **Examples:**
+
+            ```python notest
+            modal.Dict.objects.create("my-dict")
+            ```
+
+            Dicts will be created in the active environment, or another one can be specified:
+
+            ```python notest
+            modal.Dict.objects.create("my-dict", environment_name="dev")
+            ```
+
+            By default, an error will be raised if the Dict already exists, but passing
+            `allow_existing=True` will make the creation attempt a no-op in this case.
+
+            ```python notest
+            modal.Dict.objects.create("my-dict", allow_existing=True)
+            ```
+
+            Note that this method does not return a local instance of the Dict. You can use
+            `modal.Dict.from_name` to perform a lookup after creation.
+
+            Added in v1.1.2.
+            """
+            ...
+
+    create: __create_spec
+
+    class __list_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            *,
+            max_objects: typing.Optional[int] = None,
+            created_before: typing.Union[datetime.datetime, str, None] = None,
+            environment_name: str = "",
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> list[Dict]:
+            """Return a list of hydrated Dict objects.
+
+            **Examples:**
+
+            ```python
+            dicts = modal.Dict.objects.list()
+            print([d.name for d in dicts])
+            ```
+
+            Dicts will be retreived from the active environment, or another one can be specified:
+
+            ```python notest
+            dev_dicts = modal.Dict.objects.list(environment_name="dev")
+            ```
+
+            By default, all named Dict are returned, newest to oldest. It's also possible to limit the
+            number of results and to filter by creation date:
+
+            ```python
+            dicts = modal.Dict.objects.list(max_objects=10, created_before="2025-01-01")
+            ```
+
+            Added in v1.1.2.
+            """
+            ...
+
+        async def aio(
+            self,
+            /,
+            *,
+            max_objects: typing.Optional[int] = None,
+            created_before: typing.Union[datetime.datetime, str, None] = None,
+            environment_name: str = "",
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> list[Dict]:
+            """Return a list of hydrated Dict objects.
+
+            **Examples:**
+
+            ```python
+            dicts = modal.Dict.objects.list()
+            print([d.name for d in dicts])
+            ```
+
+            Dicts will be retreived from the active environment, or another one can be specified:
+
+            ```python notest
+            dev_dicts = modal.Dict.objects.list(environment_name="dev")
+            ```
+
+            By default, all named Dict are returned, newest to oldest. It's also possible to limit the
+            number of results and to filter by creation date:
+
+            ```python
+            dicts = modal.Dict.objects.list(max_objects=10, created_before="2025-01-01")
+            ```
+
+            Added in v1.1.2.
+            """
+            ...
+
+    list: __list_spec
+
+    class __delete_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            name: str,
+            *,
+            allow_missing: bool = False,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ):
+            """Delete a named Dict.
+
+            Warning: This deletes an *entire Dict*, not just a specific key.
+            Deletion is irreversible and will affect any Apps currently using the Dict.
+
+            **Examples:**
+
+            ```python notest
+            await modal.Dict.objects.delete("my-dict")
+            ```
+
+            Dicts will be deleted from the active environment, or another one can be specified:
+
+            ```python notest
+            await modal.Dict.objects.delete("my-dict", environment_name="dev")
+            ```
+
+            Added in v1.1.2.
+            """
+            ...
+
+        async def aio(
+            self,
+            /,
+            name: str,
+            *,
+            allow_missing: bool = False,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ):
+            """Delete a named Dict.
+
+            Warning: This deletes an *entire Dict*, not just a specific key.
+            Deletion is irreversible and will affect any Apps currently using the Dict.
+
+            **Examples:**
+
+            ```python notest
+            await modal.Dict.objects.delete("my-dict")
+            ```
+
+            Dicts will be deleted from the active environment, or another one can be specified:
+
+            ```python notest
+            await modal.Dict.objects.delete("my-dict", environment_name="dev")
+            ```
+
+            Added in v1.1.2.
+            """
+            ...
+
+    delete: __delete_spec
+
 class _Dict(modal._object._Object):
     """Distributed dictionary for storage in Modal apps.
 
@@ -49,10 +401,20 @@ class _Dict(modal._object._Object):
 
     For more examples, see the [guide](https://modal.com/docs/guide/dicts-and-queues#modal-dicts).
     """
+
+    _name: typing.Optional[str]
+    _metadata: typing.Optional[modal_proto.api_pb2.DictMetadata]
+
     def __init__(self, data={}):
         """mdmd:hidden"""
         ...
 
+    @synchronicity.classproperty
+    def objects(cls) -> _DictManager: ...
+    @property
+    def name(self) -> typing.Optional[str]: ...
+    def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
+    def _get_metadata(self) -> modal_proto.api_pb2.DictMetadata: ...
     @classmethod
     def ephemeral(
         cls: type[_Dict],
@@ -86,6 +448,7 @@ class _Dict(modal._object._Object):
         namespace=None,
         environment_name: typing.Optional[str] = None,
         create_if_missing: bool = False,
+        client: typing.Optional[modal.client._Client] = None,
     ) -> _Dict:
         """Reference a named Dict, creating if necessary.
 
@@ -101,36 +464,26 @@ class _Dict(modal._object._Object):
         ...
 
     @staticmethod
-    async def lookup(
+    async def delete(
         name: str,
-        data: typing.Optional[dict] = None,
-        namespace=None,
+        *,
         client: typing.Optional[modal.client._Client] = None,
         environment_name: typing.Optional[str] = None,
-        create_if_missing: bool = False,
-    ) -> _Dict:
+    ):
         """mdmd:hidden
-        Lookup a named Dict.
-
-        DEPRECATED: This method is deprecated in favor of `modal.Dict.from_name`.
+        Delete a named Dict object.
 
-        In contrast to `modal.Dict.from_name`, this is an eager method
-        that will hydrate the local object with metadata from Modal servers.
+        Warning: This deletes an *entire Dict*, not just a specific key.
+        Deletion is irreversible and will affect any Apps currently using the Dict.
 
-        ```python
-        d = modal.Dict.from_name("my-dict")
-        d["xyz"] = 123
-        ```
+        DEPRECATED: This method is deprecated; we recommend using `modal.Dict.objects.delete` instead.
         """
         ...
 
-    @staticmethod
-    async def delete(
-        name: str,
-        *,
-        client: typing.Optional[modal.client._Client] = None,
-        environment_name: typing.Optional[str] = None,
-    ): ...
+    async def info(self) -> DictInfo:
+        """Return information about the Dict object."""
+        ...
+
     async def clear(self) -> None:
         """Remove all items from the Dict."""
         ...
@@ -179,8 +532,11 @@ class _Dict(modal._object._Object):
         """
         ...
 
-    async def pop(self, key: typing.Any) -> typing.Any:
-        """Remove a key from the Dict, returning the value if it exists."""
+    async def pop(self, key: typing.Any, default: typing.Any = ...) -> typing.Any:
+        """Remove a key from the Dict, returning the value if it exists.
+
+        If key is not found, return default if provided, otherwise raise KeyError.
+        """
         ...
 
     async def __delitem__(self, key: typing.Any) -> typing.Any:
@@ -264,10 +620,20 @@ class Dict(modal.object.Object):
 
     For more examples, see the [guide](https://modal.com/docs/guide/dicts-and-queues#modal-dicts).
     """
+
+    _name: typing.Optional[str]
+    _metadata: typing.Optional[modal_proto.api_pb2.DictMetadata]
+
     def __init__(self, data={}):
         """mdmd:hidden"""
         ...
 
+    @synchronicity.classproperty
+    def objects(cls) -> DictManager: ...
+    @property
+    def name(self) -> typing.Optional[str]: ...
+    def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
+    def _get_metadata(self) -> modal_proto.api_pb2.DictMetadata: ...
     @classmethod
     def ephemeral(
         cls: type[Dict],
@@ -301,6 +667,7 @@ class Dict(modal.object.Object):
         namespace=None,
         environment_name: typing.Optional[str] = None,
         create_if_missing: bool = False,
+        client: typing.Optional[modal.client.Client] = None,
     ) -> Dict:
         """Reference a named Dict, creating if necessary.
 
@@ -315,29 +682,22 @@ class Dict(modal.object.Object):
         """
         ...
 
-    class __lookup_spec(typing_extensions.Protocol):
+    class __delete_spec(typing_extensions.Protocol):
         def __call__(
             self,
             /,
             name: str,
-            data: typing.Optional[dict] = None,
-            namespace=None,
+            *,
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
-            create_if_missing: bool = False,
-        ) -> Dict:
+        ):
             """mdmd:hidden
-            Lookup a named Dict.
-
-            DEPRECATED: This method is deprecated in favor of `modal.Dict.from_name`.
+            Delete a named Dict object.
 
-            In contrast to `modal.Dict.from_name`, this is an eager method
-            that will hydrate the local object with metadata from Modal servers.
+            Warning: This deletes an *entire Dict*, not just a specific key.
+            Deletion is irreversible and will affect any Apps currently using the Dict.
 
-            ```python
-            d = modal.Dict.from_name("my-dict")
-            d["xyz"] = 123
-            ```
+            DEPRECATED: This method is deprecated; we recommend using `modal.Dict.objects.delete` instead.
             """
             ...
 
@@ -345,48 +705,32 @@ class Dict(modal.object.Object):
             self,
             /,
             name: str,
-            data: typing.Optional[dict] = None,
-            namespace=None,
+            *,
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
-            create_if_missing: bool = False,
-        ) -> Dict:
+        ):
             """mdmd:hidden
-            Lookup a named Dict.
-
-            DEPRECATED: This method is deprecated in favor of `modal.Dict.from_name`.
+            Delete a named Dict object.
 
-            In contrast to `modal.Dict.from_name`, this is an eager method
-            that will hydrate the local object with metadata from Modal servers.
+            Warning: This deletes an *entire Dict*, not just a specific key.
+            Deletion is irreversible and will affect any Apps currently using the Dict.
 
-            ```python
-            d = modal.Dict.from_name("my-dict")
-            d["xyz"] = 123
-            ```
+            DEPRECATED: This method is deprecated; we recommend using `modal.Dict.objects.delete` instead.
             """
             ...
 
-    lookup: __lookup_spec
+    delete: __delete_spec
 
-    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,
-        ): ...
+    class __info_spec(typing_extensions.Protocol[SUPERSELF]):
+        def __call__(self, /) -> DictInfo:
+            """Return information about the Dict object."""
+            ...
 
-    delete: __delete_spec
+        async def aio(self, /) -> DictInfo:
+            """Return information about the Dict object."""
+            ...
+
+    info: __info_spec[typing_extensions.Self]
 
     class __clear_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /) -> None:
@@ -509,12 +853,18 @@ class Dict(modal.object.Object):
     __setitem__: ____setitem___spec[typing_extensions.Self]
 
     class __pop_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, key: typing.Any) -> typing.Any:
-            """Remove a key from the Dict, returning the value if it exists."""
+        def __call__(self, /, key: typing.Any, default: typing.Any = ...) -> typing.Any:
+            """Remove a key from the Dict, returning the value if it exists.
+
+            If key is not found, return default if provided, otherwise raise KeyError.
+            """
             ...
 
-        async def aio(self, /, key: typing.Any) -> typing.Any:
-            """Remove a key from the Dict, returning the value if it exists."""
+        async def aio(self, /, key: typing.Any, default: typing.Any = ...) -> typing.Any:
+            """Remove a key from the Dict, returning the value if it exists.
+
+            If key is not found, return default if provided, otherwise raise KeyError.
+            """
             ...
 
     pop: __pop_spec[typing_extensions.Self]

modal/environments.py

@@ -8,11 +8,10 @@ from google.protobuf.wrappers_pb2 import StringValue
 
 from modal_proto import api_pb2
 
+from ._load_context import LoadContext
 from ._object import _Object
 from ._resolver import Resolver
 from ._utils.async_utils import synchronize_api, synchronizer
-from ._utils.deprecation import deprecation_warning
-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
@@ -54,6 +53,7 @@ class _Environment(_Object, type_prefix="en"):
         name: str,
         *,
         create_if_missing: bool = False,
+        client: Optional[_Client] = None,
     ):
         if name:
             # Allow null names for the case where we want to look up the "default" environment,
@@ -63,7 +63,9 @@ class _Environment(_Object, type_prefix="en"):
             # 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]):
+        async def _load(
+            self: _Environment, resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]
+        ):
             request = api_pb2.EnvironmentGetOrCreateRequest(
                 deployment_name=name,
                 object_creation_type=(
@@ -72,31 +74,17 @@ class _Environment(_Object, type_prefix="en"):
                     else api_pb2.OBJECT_CREATION_TYPE_UNSPECIFIED
                 ),
             )
-            response = await retry_transient_errors(resolver.client.stub.EnvironmentGetOrCreate, request)
+            response = await load_context.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
-    async def lookup(
-        name: str,
-        client: Optional[_Client] = None,
-        create_if_missing: bool = False,
-    ):
-        deprecation_warning(
-            (2025, 1, 27),
-            "`modal.Environment.lookup` is deprecated and will be removed in a future release."
-            " It can be replaced with `modal.Environment.from_name`."
-            "\n\nSee https://modal.com/docs/guide/modal-1-0-migration for more information.",
+            self._hydrate(response.environment_id, load_context.client, response.metadata)
+
+        return _Environment._from_loader(
+            _load,
+            f"Environment.from_name({name!r})",
+            is_another_app=True,
+            hydrate_lazily=True,
+            load_context_overrides=LoadContext(client=client),
         )
-        obj = _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)
@@ -109,7 +97,7 @@ 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.from_name(name).hydrate(client)
+    environment = await _Environment.from_name(name, client=client).hydrate()
     ENVIRONMENT_CACHE[name] = environment
     return environment