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

modal/volume.pyi

@@ -1,6 +1,7 @@
 import _io
 import asyncio.locks
 import collections.abc
+import datetime
 import enum
 import google.protobuf.message
 import modal._object
@@ -9,6 +10,7 @@ import modal.client
 import modal.object
 import modal_proto.api_pb2
 import pathlib
+import synchronicity
 import synchronicity.combined_types
 import typing
 import typing_extensions
@@ -57,6 +59,350 @@ class FileEntry:
         """Return hash(self)."""
         ...
 
+class VolumeInfo:
+    """Information about the Volume 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 _VolumeManager:
+    """Namespace with methods for managing named Volume objects."""
+    @staticmethod
+    async def create(
+        name: str,
+        *,
+        version: typing.Optional[int] = None,
+        allow_existing: bool = False,
+        environment_name: typing.Optional[str] = None,
+        client: typing.Optional[modal.client._Client] = None,
+    ) -> None:
+        """Create a new Volume object.
+
+        **Examples:**
+
+        ```python notest
+        modal.Volume.objects.create("my-volume")
+        ```
+
+        Volumes will be created in the active environment, or another one can be specified:
+
+        ```python notest
+        modal.Volume.objects.create("my-volume", environment_name="dev")
+        ```
+
+        By default, an error will be raised if the Volume already exists, but passing
+        `allow_existing=True` will make the creation attempt a no-op in this case.
+
+        ```python notest
+        modal.Volume.objects.create("my-volume", allow_existing=True)
+        ```
+
+        Note that this method does not return a local instance of the Volume. You can use
+        `modal.Volume.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[_Volume]:
+        """Return a list of hydrated Volume objects.
+
+        **Examples:**
+
+        ```python
+        volumes = modal.Volume.objects.list()
+        print([v.name for v in volumes])
+        ```
+
+        Volumes will be retreived from the active environment, or another one can be specified:
+
+        ```python notest
+        dev_volumes = modal.Volume.objects.list(environment_name="dev")
+        ```
+
+        By default, all named Volumes are returned, newest to oldest. It's also possible to limit the
+        number of results and to filter by creation date:
+
+        ```python
+        volumes = modal.Volume.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 Volume.
+
+        Warning: This deletes an *entire Volume*, not just a specific file.
+        Deletion is irreversible and will affect any Apps currently using the Volume.
+
+        **Examples:**
+
+        ```python notest
+        await modal.Volume.objects.delete("my-volume")
+        ```
+
+        Volumes will be deleted from the active environment, or another one can be specified:
+
+        ```python notest
+        await modal.Volume.objects.delete("my-volume", environment_name="dev")
+        ```
+
+        Added in v1.1.2.
+        """
+        ...
+
+class VolumeManager:
+    """Namespace with methods for managing named Volume 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,
+            *,
+            version: typing.Optional[int] = None,
+            allow_existing: bool = False,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> None:
+            """Create a new Volume object.
+
+            **Examples:**
+
+            ```python notest
+            modal.Volume.objects.create("my-volume")
+            ```
+
+            Volumes will be created in the active environment, or another one can be specified:
+
+            ```python notest
+            modal.Volume.objects.create("my-volume", environment_name="dev")
+            ```
+
+            By default, an error will be raised if the Volume already exists, but passing
+            `allow_existing=True` will make the creation attempt a no-op in this case.
+
+            ```python notest
+            modal.Volume.objects.create("my-volume", allow_existing=True)
+            ```
+
+            Note that this method does not return a local instance of the Volume. You can use
+            `modal.Volume.from_name` to perform a lookup after creation.
+
+            Added in v1.1.2.
+            """
+            ...
+
+        async def aio(
+            self,
+            /,
+            name: str,
+            *,
+            version: typing.Optional[int] = None,
+            allow_existing: bool = False,
+            environment_name: typing.Optional[str] = None,
+            client: typing.Optional[modal.client.Client] = None,
+        ) -> None:
+            """Create a new Volume object.
+
+            **Examples:**
+
+            ```python notest
+            modal.Volume.objects.create("my-volume")
+            ```
+
+            Volumes will be created in the active environment, or another one can be specified:
+
+            ```python notest
+            modal.Volume.objects.create("my-volume", environment_name="dev")
+            ```
+
+            By default, an error will be raised if the Volume already exists, but passing
+            `allow_existing=True` will make the creation attempt a no-op in this case.
+
+            ```python notest
+            modal.Volume.objects.create("my-volume", allow_existing=True)
+            ```
+
+            Note that this method does not return a local instance of the Volume. You can use
+            `modal.Volume.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[Volume]:
+            """Return a list of hydrated Volume objects.
+
+            **Examples:**
+
+            ```python
+            volumes = modal.Volume.objects.list()
+            print([v.name for v in volumes])
+            ```
+
+            Volumes will be retreived from the active environment, or another one can be specified:
+
+            ```python notest
+            dev_volumes = modal.Volume.objects.list(environment_name="dev")
+            ```
+
+            By default, all named Volumes are returned, newest to oldest. It's also possible to limit the
+            number of results and to filter by creation date:
+
+            ```python
+            volumes = modal.Volume.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[Volume]:
+            """Return a list of hydrated Volume objects.
+
+            **Examples:**
+
+            ```python
+            volumes = modal.Volume.objects.list()
+            print([v.name for v in volumes])
+            ```
+
+            Volumes will be retreived from the active environment, or another one can be specified:
+
+            ```python notest
+            dev_volumes = modal.Volume.objects.list(environment_name="dev")
+            ```
+
+            By default, all named Volumes are returned, newest to oldest. It's also possible to limit the
+            number of results and to filter by creation date:
+
+            ```python
+            volumes = modal.Volume.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 Volume.
+
+            Warning: This deletes an *entire Volume*, not just a specific file.
+            Deletion is irreversible and will affect any Apps currently using the Volume.
+
+            **Examples:**
+
+            ```python notest
+            await modal.Volume.objects.delete("my-volume")
+            ```
+
+            Volumes will be deleted from the active environment, or another one can be specified:
+
+            ```python notest
+            await modal.Volume.objects.delete("my-volume", 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 Volume.
+
+            Warning: This deletes an *entire Volume*, not just a specific file.
+            Deletion is irreversible and will affect any Apps currently using the Volume.
+
+            **Examples:**
+
+            ```python notest
+            await modal.Volume.objects.delete("my-volume")
+            ```
+
+            Volumes will be deleted from the active environment, or another one can be specified:
+
+            ```python notest
+            await modal.Volume.objects.delete("my-volume", environment_name="dev")
+            ```
+
+            Added in v1.1.2.
+            """
+            ...
+
+    delete: __delete_spec
+
 class _Volume(modal._object._Object):
     """A writeable volume that can be used to share files between one or more Modal functions.
 
@@ -103,6 +449,10 @@ class _Volume(modal._object._Object):
     _metadata: typing.Optional[modal_proto.api_pb2.VolumeMetadata]
     _read_only: bool
 
+    @synchronicity.classproperty
+    def objects(cls) -> _VolumeManager: ...
+    @property
+    def name(self) -> typing.Optional[str]: ...
     def read_only(self) -> _Volume:
         """Configure Volume to mount as read-only.
 
@@ -121,10 +471,16 @@ class _Volume(modal._object._Object):
 
         The Volume is mounted as a read-only volume in a function. Any file system write operation into the
         mounted volume will result in an error.
+
+        Added in v1.0.5.
         """
         ...
 
+    def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
+    def _get_metadata(self) -> typing.Optional[google.protobuf.message.Message]: ...
     async def _get_lock(self): ...
+    @property
+    def _is_v1(self) -> bool: ...
     @staticmethod
     def from_name(
         name: str,
@@ -133,6 +489,7 @@ class _Volume(modal._object._Object):
         environment_name: typing.Optional[str] = None,
         create_if_missing: bool = False,
         version: typing.Optional[int] = None,
+        client: typing.Optional[modal.client._Client] = None,
     ) -> _Volume:
         """Reference a Volume by name, creating if necessary.
 
@@ -153,10 +510,6 @@ class _Volume(modal._object._Object):
         """
         ...
 
-    def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
-    def _get_metadata(self) -> typing.Optional[google.protobuf.message.Message]: ...
-    @property
-    def _is_v1(self) -> bool: ...
     @classmethod
     def ephemeral(
         cls: type[_Volume],
@@ -182,31 +535,18 @@ class _Volume(modal._object._Object):
         ...
 
     @staticmethod
-    async def lookup(
-        name: str,
+    async def create_deployed(
+        deployment_name: str,
         namespace=None,
         client: typing.Optional[modal.client._Client] = None,
         environment_name: typing.Optional[str] = None,
-        create_if_missing: bool = False,
         version: typing.Optional[int] = None,
-    ) -> _Volume:
-        """mdmd:hidden
-        Lookup a named Volume.
-
-        DEPRECATED: This method is deprecated in favor of `modal.Volume.from_name`.
-
-        In contrast to `modal.Volume.from_name`, this is an eager method
-        that will hydrate the local object with metadata from Modal servers.
-
-        ```python notest
-        vol = modal.Volume.from_name("my-volume")
-        print(vol.listdir("/"))
-        ```
-        """
+    ) -> str:
+        """mdmd:hidden"""
         ...
 
     @staticmethod
-    async def create_deployed(
+    async def _create_deployed(
         deployment_name: str,
         namespace=None,
         client: typing.Optional[modal.client._Client] = None,
@@ -216,9 +556,13 @@ class _Volume(modal._object._Object):
         """mdmd:hidden"""
         ...
 
+    async def info(self) -> VolumeInfo:
+        """Return information about the Volume object."""
+        ...
+
     async def _do_reload(self, lock=True): ...
     async def commit(self):
-        """Commit changes to the volume.
+        """Commit changes to a mounted volume.
 
         If successful, the changes made are now persisted in durable storage and available to other containers accessing
         the volume.
@@ -283,6 +627,14 @@ class _Volume(modal._object._Object):
         """
         ...
 
+    async def _read_file_into_fileobj(
+        self,
+        path: str,
+        fileobj: typing.IO[bytes],
+        concurrency: typing.Optional[int] = None,
+        download_semaphore: typing.Optional[asyncio.locks.Semaphore] = None,
+        progress_cb: typing.Optional[collections.abc.Callable[..., typing.Any]] = None,
+    ) -> int: ...
     async def remove_file(self, path: str, recursive: bool = False) -> None:
         """Remove a file or directory from a volume."""
         ...
@@ -337,7 +689,17 @@ class _Volume(modal._object._Object):
     @staticmethod
     async def delete(
         name: str, client: typing.Optional[modal.client._Client] = None, environment_name: typing.Optional[str] = None
-    ): ...
+    ):
+        """mdmd:hidden
+        Delete a named Volume.
+
+        Warning: This deletes an *entire Volume*, not just a specific file.
+        Deletion is irreversible and will affect any Apps currently using the Volume.
+
+        DEPRECATED: This method is deprecated; we recommend using `modal.Volume.objects.delete` instead.
+        """
+        ...
+
     @staticmethod
     async def rename(
         old_name: str,
@@ -399,6 +761,10 @@ class Volume(modal.object.Object):
         """mdmd:hidden"""
         ...
 
+    @synchronicity.classproperty
+    def objects(cls) -> VolumeManager: ...
+    @property
+    def name(self) -> typing.Optional[str]: ...
     def read_only(self) -> Volume:
         """Configure Volume to mount as read-only.
 
@@ -417,15 +783,22 @@ class Volume(modal.object.Object):
 
         The Volume is mounted as a read-only volume in a function. Any file system write operation into the
         mounted volume will result in an error.
+
+        Added in v1.0.5.
         """
         ...
 
+    def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
+    def _get_metadata(self) -> typing.Optional[google.protobuf.message.Message]: ...
+
     class ___get_lock_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /): ...
         async def aio(self, /): ...
 
     _get_lock: ___get_lock_spec[typing_extensions.Self]
 
+    @property
+    def _is_v1(self) -> bool: ...
     @staticmethod
     def from_name(
         name: str,
@@ -434,6 +807,7 @@ class Volume(modal.object.Object):
         environment_name: typing.Optional[str] = None,
         create_if_missing: bool = False,
         version: typing.Optional[int] = None,
+        client: typing.Optional[modal.client.Client] = None,
     ) -> Volume:
         """Reference a Volume by name, creating if necessary.
 
@@ -454,10 +828,6 @@ class Volume(modal.object.Object):
         """
         ...
 
-    def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
-    def _get_metadata(self) -> typing.Optional[google.protobuf.message.Message]: ...
-    @property
-    def _is_v1(self) -> bool: ...
     @classmethod
     def ephemeral(
         cls: type[Volume],
@@ -482,60 +852,34 @@ class Volume(modal.object.Object):
         """
         ...
 
-    class __lookup_spec(typing_extensions.Protocol):
+    class __create_deployed_spec(typing_extensions.Protocol):
         def __call__(
             self,
             /,
-            name: str,
+            deployment_name: str,
             namespace=None,
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
-            create_if_missing: bool = False,
             version: typing.Optional[int] = None,
-        ) -> Volume:
-            """mdmd:hidden
-            Lookup a named Volume.
-
-            DEPRECATED: This method is deprecated in favor of `modal.Volume.from_name`.
-
-            In contrast to `modal.Volume.from_name`, this is an eager method
-            that will hydrate the local object with metadata from Modal servers.
-
-            ```python notest
-            vol = modal.Volume.from_name("my-volume")
-            print(vol.listdir("/"))
-            ```
-            """
+        ) -> str:
+            """mdmd:hidden"""
             ...
 
         async def aio(
             self,
             /,
-            name: str,
+            deployment_name: str,
             namespace=None,
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
-            create_if_missing: bool = False,
             version: typing.Optional[int] = None,
-        ) -> Volume:
-            """mdmd:hidden
-            Lookup a named Volume.
-
-            DEPRECATED: This method is deprecated in favor of `modal.Volume.from_name`.
-
-            In contrast to `modal.Volume.from_name`, this is an eager method
-            that will hydrate the local object with metadata from Modal servers.
-
-            ```python notest
-            vol = modal.Volume.from_name("my-volume")
-            print(vol.listdir("/"))
-            ```
-            """
+        ) -> str:
+            """mdmd:hidden"""
             ...
 
-    lookup: __lookup_spec
+    create_deployed: __create_deployed_spec
 
-    class __create_deployed_spec(typing_extensions.Protocol):
+    class ___create_deployed_spec(typing_extensions.Protocol):
         def __call__(
             self,
             /,
@@ -560,7 +904,18 @@ class Volume(modal.object.Object):
             """mdmd:hidden"""
             ...
 
-    create_deployed: __create_deployed_spec
+    _create_deployed: ___create_deployed_spec
+
+    class __info_spec(typing_extensions.Protocol[SUPERSELF]):
+        def __call__(self, /) -> VolumeInfo:
+            """Return information about the Volume object."""
+            ...
+
+        async def aio(self, /) -> VolumeInfo:
+            """Return information about the Volume object."""
+            ...
+
+    info: __info_spec[typing_extensions.Self]
 
     class ___do_reload_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /, lock=True): ...
@@ -570,7 +925,7 @@ class Volume(modal.object.Object):
 
     class __commit_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /):
-            """Commit changes to the volume.
+            """Commit changes to a mounted volume.
 
             If successful, the changes made are now persisted in durable storage and available to other containers accessing
             the volume.
@@ -578,7 +933,7 @@ class Volume(modal.object.Object):
             ...
 
         async def aio(self, /):
-            """Commit changes to the volume.
+            """Commit changes to a mounted volume.
 
             If successful, the changes made are now persisted in durable storage and available to other containers accessing
             the volume.
@@ -720,6 +1075,28 @@ class Volume(modal.object.Object):
 
     read_file_into_fileobj: __read_file_into_fileobj_spec[typing_extensions.Self]
 
+    class ___read_file_into_fileobj_spec(typing_extensions.Protocol[SUPERSELF]):
+        def __call__(
+            self,
+            /,
+            path: str,
+            fileobj: typing.IO[bytes],
+            concurrency: typing.Optional[int] = None,
+            download_semaphore: typing.Optional[asyncio.locks.Semaphore] = None,
+            progress_cb: typing.Optional[collections.abc.Callable[..., typing.Any]] = None,
+        ) -> int: ...
+        async def aio(
+            self,
+            /,
+            path: str,
+            fileobj: typing.IO[bytes],
+            concurrency: typing.Optional[int] = None,
+            download_semaphore: typing.Optional[asyncio.locks.Semaphore] = None,
+            progress_cb: typing.Optional[collections.abc.Callable[..., typing.Any]] = None,
+        ) -> int: ...
+
+    _read_file_into_fileobj: ___read_file_into_fileobj_spec[typing_extensions.Self]
+
     class __remove_file_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /, path: str, recursive: bool = False) -> None:
             """Remove a file or directory from a volume."""
@@ -840,14 +1217,33 @@ class Volume(modal.object.Object):
             name: str,
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
-        ): ...
+        ):
+            """mdmd:hidden
+            Delete a named Volume.
+
+            Warning: This deletes an *entire Volume*, not just a specific file.
+            Deletion is irreversible and will affect any Apps currently using the Volume.
+
+            DEPRECATED: This method is deprecated; we recommend using `modal.Volume.objects.delete` instead.
+            """
+            ...
+
         async def aio(
             self,
             /,
             name: str,
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
-        ): ...
+        ):
+            """mdmd:hidden
+            Delete a named Volume.
+
+            Warning: This deletes an *entire Volume*, not just a specific file.
+            Deletion is irreversible and will affect any Apps currently using the Volume.
+
+            DEPRECATED: This method is deprecated; we recommend using `modal.Volume.objects.delete` instead.
+            """
+            ...
 
     delete: __delete_spec