modal 1.0.3.dev10__py3-none-any.whl → 1.2.3.dev7__py3-none-any.whl

modal/volume.py

@@ -11,6 +11,7 @@ import time
 import typing
 from collections.abc import AsyncGenerator, AsyncIterator, Generator, Sequence
 from dataclasses import dataclass
+from datetime import datetime
 from io import BytesIO
 from pathlib import Path, PurePosixPath
 from typing import (
@@ -24,13 +25,22 @@ from typing import (
 
 from google.protobuf.message import Message
 from grpclib import GRPCError, Status
+from synchronicity import classproperty
 from synchronicity.async_wrap import asynccontextmanager
 
+import modal.exception
 import modal_proto.api_pb2
-from modal.exception import InvalidError, VolumeUploadTimeoutError
+from modal.exception import AlreadyExistsError, InvalidError, NotFoundError, VolumeUploadTimeoutError
 from modal_proto import api_pb2
 
-from ._object import EPHEMERAL_OBJECT_HEARTBEAT_SLEEP, _get_environment_name, _Object, live_method, live_method_gen
+from ._load_context import LoadContext
+from ._object import (
+    EPHEMERAL_OBJECT_HEARTBEAT_SLEEP,
+    _get_environment_name,
+    _Object,
+    live_method,
+    live_method_gen,
+)
 from ._resolver import Resolver
 from ._utils.async_utils import (
     TaskContext,
@@ -45,15 +55,15 @@ from ._utils.blob_utils import (
     BLOCK_SIZE,
     FileUploadSpec,
     FileUploadSpec2,
-    blob_iter,
     blob_upload_file,
     get_file_upload_spec_from_fileobj,
     get_file_upload_spec_from_path,
 )
-from ._utils.deprecation import deprecation_warning
-from ._utils.grpc_utils import retry_transient_errors
+from ._utils.deprecation import deprecation_warning, warn_if_passing_namespace
+from ._utils.grpc_utils import Retry
 from ._utils.http_utils import ClientSessionRegistry
 from ._utils.name_utils import check_object_name
+from ._utils.time_utils import as_timestamp, timestamp_to_localized_dt
 from .client import _Client
 from .config import logger
 
@@ -92,6 +102,191 @@ class FileEntry:
         )
 
 
+@dataclass
+class VolumeInfo:
+    """Information about the Volume object."""
+
+    # This dataclass should be limited to information that is unchanging over the lifetime of the Volume,
+    # since it is transmitted from the server when the object is hydrated and could be stale when accessed.
+
+    name: Optional[str]
+    created_at: datetime
+    created_by: Optional[str]
+
+
+class _VolumeManager:
+    """Namespace with methods for managing named Volume objects."""
+
+    @staticmethod
+    async def create(
+        name: str,  # Name to use for the new Volume
+        *,
+        version: Optional[int] = None,  # Experimental: Configure the backend VolumeFS version
+        allow_existing: bool = False,  # If True, no-op when the Volume already exists
+        environment_name: Optional[str] = None,  # Uses active environment if not specified
+        client: Optional[_Client] = None,  # Optional client with Modal credentials
+    ) -> 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.
+
+        """
+        check_object_name(name, "Volume")
+        client = await _Client.from_env() if client is None else client
+        object_creation_type = (
+            api_pb2.OBJECT_CREATION_TYPE_CREATE_IF_MISSING
+            if allow_existing
+            else api_pb2.OBJECT_CREATION_TYPE_CREATE_FAIL_IF_EXISTS
+        )
+
+        if version is not None and version not in {1, 2}:
+            raise InvalidError("VolumeFS version must be either 1 or 2")
+
+        req = api_pb2.VolumeGetOrCreateRequest(
+            deployment_name=name,
+            environment_name=_get_environment_name(environment_name),
+            object_creation_type=object_creation_type,
+            version=version,
+        )
+        try:
+            await client.stub.VolumeGetOrCreate(req)
+        except GRPCError as exc:
+            if exc.status == Status.ALREADY_EXISTS and not allow_existing:
+                raise AlreadyExistsError(exc.message)
+            else:
+                raise
+
+    @staticmethod
+    async def list(
+        *,
+        max_objects: Optional[int] = None,  # Limit requests to this size
+        created_before: Optional[Union[datetime, str]] = None,  # Limit based on creation date
+        environment_name: str = "",  # Uses active environment if not specified
+        client: Optional[_Client] = None,  # Optional client with Modal credentials
+    ) -> 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.
+
+        """
+        client = await _Client.from_env() if client is None else client
+        if max_objects is not None and max_objects < 0:
+            raise InvalidError("max_objects cannot be negative")
+
+        items: list[api_pb2.VolumeListItem] = []
+
+        async def retrieve_page(created_before: float) -> bool:
+            max_page_size = 100 if max_objects is None else min(100, max_objects - len(items))
+            pagination = api_pb2.ListPagination(max_objects=max_page_size, created_before=created_before)
+            req = api_pb2.VolumeListRequest(
+                environment_name=_get_environment_name(environment_name), pagination=pagination
+            )
+            resp = await client.stub.VolumeList(req)
+            items.extend(resp.items)
+            finished = (len(resp.items) < max_page_size) or (max_objects is not None and len(items) >= max_objects)
+            return finished
+
+        finished = await retrieve_page(as_timestamp(created_before))
+        while True:
+            if finished:
+                break
+            finished = await retrieve_page(items[-1].metadata.creation_info.created_at)
+
+        volumes = [
+            _Volume._new_hydrated(
+                item.volume_id,
+                client,
+                item.metadata,
+                is_another_app=True,
+                rep=_Volume._repr(item.label, environment_name),
+            )
+            for item in items
+        ]
+        return volumes[:max_objects] if max_objects is not None else volumes
+
+    @staticmethod
+    async def delete(
+        name: str,  # Name of the Volume to delete
+        *,
+        allow_missing: bool = False,  # If True, don't raise an error if the Volume doesn't exist
+        environment_name: Optional[str] = None,  # Uses active environment if not specified
+        client: Optional[_Client] = None,  # Optional client with Modal credentials
+    ):
+        """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.
+
+        """
+        try:
+            obj = await _Volume.from_name(name, environment_name=environment_name).hydrate(client)
+        except NotFoundError:
+            if not allow_missing:
+                raise
+        else:
+            req = api_pb2.VolumeDeleteRequest(volume_id=obj.object_id)
+            await obj._client.stub.VolumeDelete(req)
+
+
+VolumeManager = synchronize_api(_VolumeManager)
+
+
 class _Volume(_Object, type_prefix="vo"):
     """A writeable volume that can be used to share files between one or more Modal functions.
 
@@ -136,6 +331,61 @@ class _Volume(_Object, type_prefix="vo"):
 
     _lock: Optional[asyncio.Lock] = None
     _metadata: "typing.Optional[api_pb2.VolumeMetadata]"
+    _read_only: bool = False
+
+    @classproperty
+    def objects(cls) -> _VolumeManager:
+        return _VolumeManager
+
+    @property
+    def name(self) -> Optional[str]:
+        return self._name
+
+    def read_only(self) -> "_Volume":
+        """Configure Volume to mount as read-only.
+
+        **Example**
+
+        ```python
+        import modal
+
+        volume = modal.Volume.from_name("my-volume", create_if_missing=True)
+
+        @app.function(volumes={"/mnt/items": volume.read_only()})
+        def f():
+            with open("/mnt/items/my-file.txt") as f:
+                return f.read()
+        ```
+
+        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.
+        """
+
+        async def _load(
+            new_volume: _Volume, resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]
+        ):
+            new_volume._initialize_from_other(self)
+            new_volume._read_only = True
+
+        obj = _Volume._from_loader(
+            _load,
+            "Volume()",
+            hydrate_lazily=True,
+            deps=lambda: [self],
+            load_context_overrides=self._load_context_overrides,
+        )
+        return obj
+
+    def _hydrate_metadata(self, metadata: Optional[Message]):
+        if metadata:
+            assert isinstance(metadata, api_pb2.VolumeMetadata)
+            self._metadata = metadata
+            self._name = metadata.name
+
+    def _get_metadata(self) -> Optional[Message]:
+        return self._metadata
 
     async def _get_lock(self):
         # To (mostly*) prevent multiple concurrent operations on the same volume, which can cause problems under
@@ -151,20 +401,29 @@ class _Volume(_Object, type_prefix="vo"):
             self._lock = asyncio.Lock()
         return self._lock
 
+    @property
+    def _is_v1(self) -> bool:
+        return self._metadata.version in [
+            None,
+            api_pb2.VolumeFsVersion.VOLUME_FS_VERSION_UNSPECIFIED,
+            api_pb2.VolumeFsVersion.VOLUME_FS_VERSION_V1,
+        ]
+
     @staticmethod
     def from_name(
         name: str,
         *,
-        namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
+        namespace=None,  # mdmd:line-hidden
         environment_name: Optional[str] = None,
         create_if_missing: bool = False,
         version: "typing.Optional[modal_proto.api_pb2.VolumeFsVersion.ValueType]" = None,
+        client: Optional[_Client] = None,
     ) -> "_Volume":
         """Reference a Volume by name, creating if necessary.
 
-        In contrast to `modal.Volume.lookup`, this is a lazy method
-        that defers hydrating the local object with metadata from
-        Modal servers until the first time is is actually used.
+        This is a lazy method that defers hydrating the local
+        object with metadata from Modal servers until the first
+        time is is actually used.
 
         ```python
         vol = modal.Volume.from_name("my-volume", create_if_missing=True)
@@ -178,36 +437,28 @@ class _Volume(_Object, type_prefix="vo"):
         ```
         """
         check_object_name(name, "Volume")
+        warn_if_passing_namespace(namespace, "modal.Volume.from_name")
 
-        async def _load(self: _Volume, resolver: Resolver, existing_object_id: Optional[str]):
+        async def _load(
+            self: _Volume, resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]
+        ):
             req = api_pb2.VolumeGetOrCreateRequest(
                 deployment_name=name,
-                namespace=namespace,
-                environment_name=_get_environment_name(environment_name, resolver),
+                environment_name=load_context.environment_name,
                 object_creation_type=(api_pb2.OBJECT_CREATION_TYPE_CREATE_IF_MISSING if create_if_missing else None),
                 version=version,
             )
-            response = await resolver.client.stub.VolumeGetOrCreate(req)
-            self._hydrate(response.volume_id, resolver.client, response.metadata)
-
-        return _Volume._from_loader(_load, "Volume()", hydrate_lazily=True)
-
-    def _hydrate_metadata(self, metadata: Optional[Message]):
-        if metadata and isinstance(metadata, api_pb2.VolumeMetadata):
-            self._metadata = metadata
-        else:
-            raise TypeError("_hydrate_metadata() requires an `api_pb2.VolumeMetadata` to determine volume version")
-
-    def _get_metadata(self) -> Optional[Message]:
-        return self._metadata
-
-    @property
-    def _is_v1(self) -> bool:
-        return self._metadata.version in [
-            None,
-            api_pb2.VolumeFsVersion.VOLUME_FS_VERSION_UNSPECIFIED,
-            api_pb2.VolumeFsVersion.VOLUME_FS_VERSION_V1,
-        ]
+            response = await load_context.client.stub.VolumeGetOrCreate(req)
+            self._hydrate(response.volume_id, load_context.client, response.metadata)
+
+        rep = _Volume._repr(name, environment_name)
+        return _Volume._from_loader(
+            _load,
+            rep,
+            hydrate_lazily=True,
+            name=name,
+            load_context_overrides=LoadContext(client=client, environment_name=environment_name),
+        )
 
     @classmethod
     @asynccontextmanager
@@ -216,7 +467,7 @@ class _Volume(_Object, type_prefix="vo"):
         client: Optional[_Client] = None,
         environment_name: Optional[str] = None,
         version: "typing.Optional[modal_proto.api_pb2.VolumeFsVersion.ValueType]" = None,
-        _heartbeat_sleep: float = EPHEMERAL_OBJECT_HEARTBEAT_SLEEP,
+        _heartbeat_sleep: float = EPHEMERAL_OBJECT_HEARTBEAT_SLEEP,  # mdmd:line-hidden
     ) -> AsyncGenerator["_Volume", None]:
         """Creates a new ephemeral volume within a context manager:
 
@@ -243,80 +494,74 @@ class _Volume(_Object, type_prefix="vo"):
         async with TaskContext() as tc:
             request = api_pb2.VolumeHeartbeatRequest(volume_id=response.volume_id)
             tc.infinite_loop(lambda: client.stub.VolumeHeartbeat(request), sleep=_heartbeat_sleep)
-            yield cls._new_hydrated(response.volume_id, client, response.metadata, is_another_app=True)
+            yield cls._new_hydrated(
+                response.volume_id,
+                client,
+                response.metadata,
+                is_another_app=True,
+                rep="modal.Volume.ephemeral()",
+            )
 
     @staticmethod
-    async def lookup(
-        name: str,
-        namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
+    async def create_deployed(
+        deployment_name: str,
+        namespace=None,  # mdmd:line-hidden
         client: Optional[_Client] = None,
         environment_name: Optional[str] = None,
-        create_if_missing: bool = False,
         version: "typing.Optional[modal_proto.api_pb2.VolumeFsVersion.ValueType]" = 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"""
         deprecation_warning(
-            (2025, 1, 27),
-            "`modal.Volume.lookup` is deprecated and will be removed in a future release."
-            " It can be replaced with `modal.Volume.from_name`."
-            "\n\nSee https://modal.com/docs/guide/modal-1-0-migration for more information.",
-        )
-        obj = _Volume.from_name(
-            name,
-            namespace=namespace,
-            environment_name=environment_name,
-            create_if_missing=create_if_missing,
-            version=version,
+            (2025, 8, 13),
+            "The undocumented `modal.Volume.create_deployed` method is deprecated and will be removed "
+            "in a future release. It can be replaced with `modal.Volume.objects.create`.",
         )
-        if client is None:
-            client = await _Client.from_env()
-        resolver = Resolver(client=client)
-        await resolver.load(obj)
-        return obj
+        return await _Volume._create_deployed(deployment_name, namespace, client, environment_name, version)
 
     @staticmethod
-    async def create_deployed(
+    async def _create_deployed(
         deployment_name: str,
-        namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
+        namespace=None,  # mdmd:line-hidden
         client: Optional[_Client] = None,
         environment_name: Optional[str] = None,
         version: "typing.Optional[modal_proto.api_pb2.VolumeFsVersion.ValueType]" = None,
     ) -> str:
         """mdmd:hidden"""
         check_object_name(deployment_name, "Volume")
+        warn_if_passing_namespace(namespace, "modal.Volume.create_deployed")
         if client is None:
             client = await _Client.from_env()
         request = api_pb2.VolumeGetOrCreateRequest(
             deployment_name=deployment_name,
-            namespace=namespace,
             environment_name=_get_environment_name(environment_name),
             object_creation_type=api_pb2.OBJECT_CREATION_TYPE_CREATE_FAIL_IF_EXISTS,
             version=version,
         )
-        resp = await retry_transient_errors(client.stub.VolumeGetOrCreate, request)
+        resp = await client.stub.VolumeGetOrCreate(request)
         return resp.volume_id
 
+    @live_method
+    async def info(self) -> VolumeInfo:
+        """Return information about the Volume object."""
+        metadata = self._get_metadata()
+        if not metadata:
+            return VolumeInfo()
+        creation_info = metadata.creation_info
+        return VolumeInfo(
+            name=metadata.name or None,
+            created_at=timestamp_to_localized_dt(creation_info.created_at),
+            created_by=creation_info.created_by or None,
+        )
+
     @live_method
     async def _do_reload(self, lock=True):
         async with (await self._get_lock()) if lock else asyncnullcontext():
             req = api_pb2.VolumeReloadRequest(volume_id=self.object_id)
-            _ = await retry_transient_errors(self._client.stub.VolumeReload, req)
+            _ = await self._client.stub.VolumeReload(req)
 
     @live_method
     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.
@@ -325,7 +570,7 @@ class _Volume(_Object, type_prefix="vo"):
             req = api_pb2.VolumeCommitRequest(volume_id=self.object_id)
             try:
                 # TODO(gongy): only apply indefinite retries on 504 status.
-                resp = await retry_transient_errors(self._client.stub.VolumeCommit, req, max_retries=90)
+                resp = await self._client.stub.VolumeCommit(req, retry=Retry(max_retries=90))
                 if not resp.skip_reload:
                     # Reload changes on successful commit.
                     await self._do_reload(lock=False)
@@ -400,10 +645,14 @@ class _Volume(_Object, type_prefix="vo"):
         return [entry async for entry in self.iterdir(path, recursive=recursive)]
 
     @live_method_gen
-    def read_file(self, path: str) -> AsyncIterator[bytes]:
+    async def read_file(self, path: str) -> AsyncIterator[bytes]:
         """
         Read a file from the modal.Volume.
 
+        Note - this function is primarily intended to be used outside of a Modal App.
+        For more information on downloading files from a Modal Volume, see
+        [the guide](https://modal.com/docs/guide/volumes).
+
         **Example:**
 
         ```python notest
@@ -414,32 +663,17 @@ class _Volume(_Object, type_prefix="vo"):
         print(len(data))  # == 1024 * 1024
         ```
         """
-        return self._read_file1(path) if self._is_v1 else self._read_file2(path)
-
-    async def _read_file1(self, path: str) -> AsyncIterator[bytes]:
-        req = api_pb2.VolumeGetFileRequest(volume_id=self.object_id, path=path)
-        try:
-            response = await retry_transient_errors(self._client.stub.VolumeGetFile, req)
-        except GRPCError as exc:
-            raise FileNotFoundError(exc.message) if exc.status == Status.NOT_FOUND else exc
-        # TODO(Jonathon): use ranged requests.
-        if response.WhichOneof("data_oneof") == "data":
-            yield response.data
-            return
-        else:
-            async for data in blob_iter(response.data_blob_id, self._client.stub):
-                yield data
-
-    async def _read_file2(self, path: str) -> AsyncIterator[bytes]:
         req = api_pb2.VolumeGetFile2Request(volume_id=self.object_id, path=path)
 
         try:
-            response = await retry_transient_errors(self._client.stub.VolumeGetFile2, req)
-        except GRPCError as exc:
-            raise FileNotFoundError(exc.message) if exc.status == Status.NOT_FOUND else exc
+            response = await self._client.stub.VolumeGetFile2(req)
+        except modal.exception.NotFoundError as exc:
+            raise FileNotFoundError(exc.args[0])
 
+        @retry(n_attempts=5, base_delay=0.1, timeout=None)
         async def read_block(block_url: str) -> bytes:
             async with ClientSessionRegistry.get_session().get(block_url) as get_response:
+                get_response.raise_for_status()
                 return await get_response.content.read()
 
         async def iter_urls() -> AsyncGenerator[str]:
@@ -455,59 +689,53 @@ class _Volume(_Object, type_prefix="vo"):
 
     @live_method
     async def read_file_into_fileobj(
-        self, path: str, fileobj: typing.IO[bytes], progress_cb: Optional[Callable[..., Any]] = None
+        self,
+        path: str,
+        fileobj: typing.IO[bytes],
+        progress_cb: Optional[Callable[..., Any]] = None,
     ) -> int:
         """mdmd:hidden
         Read volume file into file-like IO object.
         """
+        return await self._read_file_into_fileobj(path, fileobj, progress_cb=progress_cb)
+
+    @live_method
+    async def _read_file_into_fileobj(
+        self,
+        path: str,
+        fileobj: typing.IO[bytes],
+        concurrency: Optional[int] = None,
+        download_semaphore: Optional[asyncio.Semaphore] = None,
+        progress_cb: Optional[Callable[..., Any]] = None,
+    ) -> int:
         if progress_cb is None:
 
             def progress_cb(*_, **__):
                 pass
 
-        if self._is_v1:
-            return await self._read_file_into_fileobj1(path, fileobj, progress_cb)
-        else:
-            return await self._read_file_into_fileobj2(path, fileobj, progress_cb)
-
-    async def _read_file_into_fileobj1(
-        self, path: str, fileobj: typing.IO[bytes], progress_cb: Callable[..., Any]
-    ) -> int:
-        num_bytes_written = 0
-
-        async for chunk in self._read_file1(path):
-            num_chunk_bytes_written = 0
-
-            while num_chunk_bytes_written < len(chunk):
-                # TODO(dflemstr): this is a small write, but nonetheless might block the event loop for some time:
-                n = fileobj.write(chunk)
-                num_chunk_bytes_written += n
-                progress_cb(advance=n)
-
-            num_bytes_written += len(chunk)
+        if concurrency is None:
+            concurrency = multiprocessing.cpu_count()
 
-        return num_bytes_written
-
-    async def _read_file_into_fileobj2(
-        self, path: str, fileobj: typing.IO[bytes], progress_cb: Callable[..., Any]
-    ) -> int:
         req = api_pb2.VolumeGetFile2Request(volume_id=self.object_id, path=path)
 
         try:
-            response = await retry_transient_errors(self._client.stub.VolumeGetFile2, req)
-        except GRPCError as exc:
-            raise FileNotFoundError(exc.message) if exc.status == Status.NOT_FOUND else exc
+            response = await self._client.stub.VolumeGetFile2(req)
+        except modal.exception.NotFoundError as exc:
+            raise FileNotFoundError(exc.args[0])
+
+        if download_semaphore is None:
+            download_semaphore = asyncio.Semaphore(concurrency)
 
-        # TODO(dflemstr): Sane default limit? Make configurable?
-        download_semaphore = asyncio.Semaphore(multiprocessing.cpu_count())
         write_lock = asyncio.Lock()
         start_pos = fileobj.tell()
 
+        @retry(n_attempts=5, base_delay=0.1, timeout=None)
         async def download_block(idx, url) -> int:
             block_start_pos = start_pos + idx * BLOCK_SIZE
             num_bytes_written = 0
 
             async with download_semaphore, ClientSessionRegistry.get_session().get(url) as get_response:
+                get_response.raise_for_status()
                 async for chunk in get_response.content.iter_any():
                     num_chunk_bytes_written = 0
 
@@ -535,15 +763,21 @@ class _Volume(_Object, type_prefix="vo"):
     @live_method
     async def remove_file(self, path: str, recursive: bool = False) -> None:
         """Remove a file or directory from a volume."""
-        if self._is_v1:
-            req = api_pb2.VolumeRemoveFileRequest(volume_id=self.object_id, path=path, recursive=recursive)
-            await retry_transient_errors(self._client.stub.VolumeRemoveFile, req)
-        else:
-            req = api_pb2.VolumeRemoveFile2Request(volume_id=self.object_id, path=path, recursive=recursive)
-            await retry_transient_errors(self._client.stub.VolumeRemoveFile2, req)
+        if self._read_only:
+            raise InvalidError("Read-only Volume can not be written to")
+
+        try:
+            if self._is_v1:
+                req = api_pb2.VolumeRemoveFileRequest(volume_id=self.object_id, path=path, recursive=recursive)
+                await self._client.stub.VolumeRemoveFile(req)
+            else:
+                req = api_pb2.VolumeRemoveFile2Request(volume_id=self.object_id, path=path, recursive=recursive)
+                await self._client.stub.VolumeRemoveFile2(req)
+        except modal.exception.NotFoundError as exc:
+            raise FileNotFoundError(exc.args[0])
 
     @live_method
-    async def copy_files(self, src_paths: Sequence[str], dst_path: str) -> None:
+    async def copy_files(self, src_paths: Sequence[str], dst_path: str, recursive: bool = False) -> None:
         """
         Copy files within the volume from src_paths to dst_path.
         The semantics of the copy operation follow those of the UNIX cp command.
@@ -567,8 +801,22 @@ class _Volume(_Object, type_prefix="vo"):
         like `os.rename()` and then `commit()` the volume. The `copy_files()` method is useful when you don't have
         the volume mounted as a filesystem, e.g. when running a script on your local computer.
         """
-        request = api_pb2.VolumeCopyFilesRequest(volume_id=self.object_id, src_paths=src_paths, dst_path=dst_path)
-        await retry_transient_errors(self._client.stub.VolumeCopyFiles, request, base_delay=1)
+        if self._read_only:
+            raise InvalidError("Read-only Volume can not be written to")
+
+        if self._is_v1:
+            if recursive:
+                raise ValueError("`recursive` is not supported for V1 volumes")
+
+            request = api_pb2.VolumeCopyFilesRequest(
+                volume_id=self.object_id, src_paths=src_paths, dst_path=dst_path, recursive=recursive
+            )
+            await self._client.stub.VolumeCopyFiles(request, retry=Retry(base_delay=1))
+        else:
+            request = api_pb2.VolumeCopyFiles2Request(
+                volume_id=self.object_id, src_paths=src_paths, dst_path=dst_path, recursive=recursive
+            )
+            await self._client.stub.VolumeCopyFiles2(request, retry=Retry(base_delay=1))
 
     @live_method
     async def batch_upload(self, force: bool = False) -> "_AbstractVolumeUploadContextManager":
@@ -589,21 +837,33 @@ class _Volume(_Object, type_prefix="vo"):
             batch.put_file(io.BytesIO(b"some data"), "/foobar")
         ```
         """
+        if self._read_only:
+            raise InvalidError("Read-only Volume can not be written to")
+
         return _AbstractVolumeUploadContextManager.resolve(
             self._metadata.version, self.object_id, self._client, force=force
         )
 
     @live_method
     async def _instance_delete(self):
-        await retry_transient_errors(
-            self._client.stub.VolumeDelete, api_pb2.VolumeDeleteRequest(volume_id=self.object_id)
-        )
+        await self._client.stub.VolumeDelete(api_pb2.VolumeDeleteRequest(volume_id=self.object_id))
 
     @staticmethod
     async def delete(name: str, client: Optional[_Client] = None, environment_name: Optional[str] = None):
-        obj = await _Volume.from_name(name, environment_name=environment_name).hydrate(client)
-        req = api_pb2.VolumeDeleteRequest(volume_id=obj.object_id)
-        await retry_transient_errors(obj._client.stub.VolumeDelete, req)
+        """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.
+
+        """
+        deprecation_warning(
+            (2025, 8, 6),
+            "`modal.Volume.delete` is deprecated; we recommend using `modal.Volume.objects.delete` instead.",
+        )
+        await _Volume.objects.delete(name, environment_name=environment_name, client=client)
 
     @staticmethod
     async def rename(
@@ -615,7 +875,7 @@ class _Volume(_Object, type_prefix="vo"):
     ):
         obj = await _Volume.from_name(old_name, environment_name=environment_name).hydrate(client)
         req = api_pb2.VolumeRenameRequest(volume_id=obj.object_id, name=new_name)
-        await retry_transient_errors(obj._client.stub.VolumeRename, req)
+        await obj._client.stub.VolumeRename(req)
 
 
 Volume = synchronize_api(_Volume)
@@ -716,7 +976,7 @@ class _VolumeUploadContextManager(_AbstractVolumeUploadContextManager):
                 disallow_overwrite_existing_files=not self._force,
             )
             try:
-                await retry_transient_errors(self._client.stub.VolumePutFiles, request, base_delay=1)
+                await self._client.stub.VolumePutFiles(request, retry=Retry(base_delay=1))
             except GRPCError as exc:
                 raise FileExistsError(exc.message) if exc.status == Status.ALREADY_EXISTS else exc
 
@@ -776,7 +1036,7 @@ class _VolumeUploadContextManager(_AbstractVolumeUploadContextManager):
         remote_filename = file_spec.mount_filename
         progress_task_id = self._progress_cb(name=remote_filename, size=file_spec.size)
         request = api_pb2.MountPutFileRequest(sha256_hex=file_spec.sha256_hex)
-        response = await retry_transient_errors(self._client.stub.MountPutFile, request, base_delay=1)
+        response = await self._client.stub.MountPutFile(request, retry=Retry(base_delay=1))
 
         start_time = time.monotonic()
         if not response.exists:
@@ -800,7 +1060,7 @@ class _VolumeUploadContextManager(_AbstractVolumeUploadContextManager):
                 self._progress_cb(task_id=progress_task_id, complete=True)
 
             while (time.monotonic() - start_time) < VOLUME_PUT_FILE_CLIENT_TIMEOUT:
-                response = await retry_transient_errors(self._client.stub.MountPutFile, request2, base_delay=1)
+                response = await self._client.stub.MountPutFile(request2, retry=Retry(base_delay=1))
                 if response.exists:
                     break
 
@@ -943,9 +1203,9 @@ class _VolumeUploadContextManager2(_AbstractVolumeUploadContextManager):
             for file_spec in file_specs:
                 blocks = [
                     api_pb2.VolumePutFiles2Request.Block(
-                        contents_sha256=block_sha256, put_response=put_responses.get(block_sha256)
+                        contents_sha256=block.contents_sha256, put_response=put_responses.get(block.contents_sha256)
                     )
-                    for block_sha256 in file_spec.blocks_sha256
+                    for block in file_spec.blocks
                 ]
                 files.append(
                     api_pb2.VolumePutFiles2Request.File(
@@ -960,7 +1220,7 @@ class _VolumeUploadContextManager2(_AbstractVolumeUploadContextManager):
             )
 
             try:
-                response = await retry_transient_errors(self._client.stub.VolumePutFiles2, request, base_delay=1)
+                response = await self._client.stub.VolumePutFiles2(request, retry=Retry(base_delay=1))
             except GRPCError as exc:
                 raise FileExistsError(exc.message) if exc.status == Status.ALREADY_EXISTS else exc
 
@@ -1002,7 +1262,7 @@ async def _put_missing_blocks(
         # TODO(dflemstr): Type is `api_pb2.VolumePutFiles2Response.MissingBlock` but synchronicity gets confused
         # by the nested class (?)
         missing_block,
-    ) -> (bytes, bytes):
+    ) -> tuple[bytes, bytes]:
         # Lazily import to keep the eager loading time of this module down
         from ._utils.bytes_io_segment_payload import BytesIOSegmentPayload
 
@@ -1011,9 +1271,7 @@ async def _put_missing_blocks(
         file_spec = file_specs[missing_block.file_index]
         # TODO(dflemstr): What if the underlying file has changed here in the meantime; should we check the
         #  hash again just to be sure?
-        block_sha256 = file_spec.blocks_sha256[missing_block.block_index]
-        block_start = missing_block.block_index * BLOCK_SIZE
-        block_length = min(BLOCK_SIZE, file_spec.size - block_start)
+        block = file_spec.blocks[missing_block.block_index]
 
         if file_spec.path not in file_progresses:
             file_task_id = progress_cb(name=file_spec.path, size=file_spec.size)
@@ -1023,7 +1281,7 @@ async def _put_missing_blocks(
         file_progress.pending_blocks.add(missing_block.block_index)
         task_progress_cb = functools.partial(progress_cb, task_id=file_progress.task_id)
 
-        @retry(n_attempts=5, base_delay=0.5, timeout=None)
+        @retry(n_attempts=11, base_delay=0.5, timeout=None)
         async def put_missing_block_attempt(payload: BytesIOSegmentPayload) -> bytes:
             with payload.reset_on_error(subtract_progress=True):
                 async with ClientSessionRegistry.get_session().put(
@@ -1037,8 +1295,8 @@ async def _put_missing_blocks(
             with file_spec.source() as source_fp:
                 payload = BytesIOSegmentPayload(
                     source_fp,
-                    block_start,
-                    block_length,
+                    block.start,
+                    block.end - block.start,
                     # limit chunk size somewhat to not keep event loop busy for too long
                     chunk_size=256 * 1024,
                     progress_report_cb=task_progress_cb,
@@ -1050,7 +1308,7 @@ async def _put_missing_blocks(
         if len(file_progress.pending_blocks) == 0:
             task_progress_cb(complete=True)
 
-        return block_sha256, resp_data
+        return block.contents_sha256, resp_data
 
     tasks = [asyncio.create_task(put_missing_block(missing_block)) for missing_block in missing_blocks]
     for task_result in asyncio.as_completed(tasks):