modal 0.68.1__py3-none-any.whl → 0.68.2__py3-none-any.whl

modal/client.pyi

@@ -26,7 +26,7 @@ class _Client:
     _stub: typing.Optional[modal_proto.api_grpc.ModalClientStub]
 
     def __init__(
-        self, server_url: str, client_type: int, credentials: typing.Optional[tuple[str, str]], version: str = "0.68.1"
+        self, server_url: str, client_type: int, credentials: typing.Optional[tuple[str, str]], version: str = "0.68.2"
     ): ...
     def is_closed(self) -> bool: ...
     @property
@@ -81,7 +81,7 @@ class Client:
     _stub: typing.Optional[modal_proto.api_grpc.ModalClientStub]
 
     def __init__(
-        self, server_url: str, client_type: int, credentials: typing.Optional[tuple[str, str]], version: str = "0.68.1"
+        self, server_url: str, client_type: int, credentials: typing.Optional[tuple[str, str]], version: str = "0.68.2"
     ): ...
     def is_closed(self) -> bool: ...
     @property

modal/exception.py

@@ -222,6 +222,10 @@ class ClientClosed(Error):
     pass
 
 
+class FilesystemExecutionError(Error):
+    """Raised when an unknown error is thrown during a container filesystem operation."""
+
+
 def print_server_warnings(server_warnings: Iterable[api_pb2.Warning]):
     # TODO(erikbern): move this to modal._utils.deprecation
     for warning in server_warnings:

modal/file_io.py

@@ -0,0 +1,380 @@
+# Copyright Modal Labs 2024
+import asyncio
+import io
+from typing import TYPE_CHECKING, AsyncIterator, Generic, Optional, Sequence, TypeVar, Union, cast
+
+if TYPE_CHECKING:
+    import _typeshed
+
+from grpclib.exceptions import GRPCError, StreamTerminatedError
+
+from modal._utils.grpc_utils import retry_transient_errors
+from modal_proto import api_pb2
+
+from ._utils.async_utils import synchronize_api
+from ._utils.grpc_utils import RETRYABLE_GRPC_STATUS_CODES
+from .client import _Client
+from .exception import FilesystemExecutionError, InvalidError
+
+LARGE_FILE_SIZE_LIMIT = 16 * 1024 * 1024  # 16 MiB
+READ_FILE_SIZE_LIMIT = 100 * 1024 * 1024  # 100 MiB
+
+ERROR_MAPPING = {
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_UNSPECIFIED: FilesystemExecutionError,
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_PERM: PermissionError,
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_NOENT: FileNotFoundError,
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_IO: IOError,
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_NXIO: IOError,
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_NOMEM: MemoryError,
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_ACCES: PermissionError,
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_EXIST: FileExistsError,
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_NOTDIR: NotADirectoryError,
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_ISDIR: IsADirectoryError,
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_INVAL: OSError,
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_MFILE: OSError,
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_FBIG: OSError,
+    api_pb2.SystemErrorCode.SYSTEM_ERROR_CODE_NOSPC: OSError,
+}
+
+T = TypeVar("T", str, bytes)
+
+
+async def _delete_bytes(file: "_FileIO", start: Optional[int] = None, end: Optional[int] = None) -> None:
+    """Delete a range of bytes from the file.
+
+    `start` and `end` are byte offsets. `start` is inclusive, `end` is exclusive.
+    If either is None, the start or end of the file is used, respectively.
+    """
+    assert file._file_descriptor is not None
+    file._check_closed()
+    if start is not None and end is not None:
+        if start >= end:
+            raise ValueError("start must be less than end")
+    resp = await file._make_request(
+        api_pb2.ContainerFilesystemExecRequest(
+            file_delete_bytes_request=api_pb2.ContainerFileDeleteBytesRequest(
+                file_descriptor=file._file_descriptor,
+                start_inclusive=start,
+                end_exclusive=end,
+            ),
+            task_id=file._task_id,
+        )
+    )
+    await file._wait(resp.exec_id)
+
+
+async def _replace_bytes(file: "_FileIO", data: bytes, start: Optional[int] = None, end: Optional[int] = None) -> None:
+    """Replace a range of bytes in the file with new data. The length of the data does not
+    have to be the same as the length of the range being replaced.
+
+    `start` and `end` are byte offsets. `start` is inclusive, `end` is exclusive.
+    If either is None, the start or end of the file is used, respectively.
+    """
+    assert file._file_descriptor is not None
+    file._check_closed()
+    if start is not None and end is not None:
+        if start >= end:
+            raise InvalidError("start must be less than end")
+    if len(data) > LARGE_FILE_SIZE_LIMIT:
+        raise InvalidError("Write request payload exceeds 16 MiB limit")
+    resp = await file._make_request(
+        api_pb2.ContainerFilesystemExecRequest(
+            file_write_replace_bytes_request=api_pb2.ContainerFileWriteReplaceBytesRequest(
+                file_descriptor=file._file_descriptor,
+                data=data,
+                start_inclusive=start,
+                end_exclusive=end,
+            ),
+            task_id=file._task_id,
+        )
+    )
+    await file._wait(resp.exec_id)
+
+
+# The FileIO class is designed to mimic Python's io.FileIO
+# See https://github.com/python/cpython/blob/main/Lib/_pyio.py#L1459
+class _FileIO(Generic[T]):
+    """FileIO handle, used in the Sandbox filesystem API.
+
+    The API is designed to mimic Python's io.FileIO.
+
+    **Usage**
+
+    ```python
+    import modal
+
+    app = modal.App.lookup("my-app", create_if_missing=True)
+
+    sb = modal.Sandbox.create(app=app)
+    f = sb.open("/tmp/foo.txt", "w")
+    f.write("hello")
+    f.close()
+    ```
+    """
+
+    _binary = False
+    _readable = False
+    _writable = False
+    _appended = False
+    _closed = True
+
+    _task_id: str = ""
+    _file_descriptor: str = ""
+    _client: Optional[_Client] = None
+
+    def _validate_mode(self, mode: str) -> None:
+        if not any(char in mode for char in "rwax"):
+            raise ValueError(f"Invalid file mode: {mode}")
+
+        self._readable = "r" in mode or "+" in mode
+        self._writable = "w" in mode or "a" in mode or "x" in mode or "+" in mode
+        self._appended = "a" in mode
+        self._binary = "b" in mode
+
+        valid_chars = set("rwaxb+")
+        if any(char not in valid_chars for char in mode):
+            raise ValueError(f"Invalid file mode: {mode}")
+
+        mode_count = sum(1 for c in mode if c in "rwax")
+        if mode_count > 1:
+            raise ValueError("must have exactly one of create/read/write/append mode")
+
+        seen_chars = set()
+        for char in mode:
+            if char in seen_chars:
+                raise ValueError(f"Invalid file mode: {mode}")
+            seen_chars.add(char)
+
+    def _handle_error(self, error: api_pb2.SystemErrorMessage) -> None:
+        error_class = ERROR_MAPPING.get(error.error_code, FilesystemExecutionError)
+        raise error_class(error.error_message)
+
+    async def _consume_output(self, exec_id: str) -> AsyncIterator[Optional[bytes]]:
+        req = api_pb2.ContainerFilesystemExecGetOutputRequest(
+            exec_id=exec_id,
+            timeout=55,
+        )
+        assert self._client is not None
+        async for batch in self._client.stub.ContainerFilesystemExecGetOutput.unary_stream(req):
+            if batch.eof:
+                yield None
+                break
+            if batch.HasField("error"):
+                self._handle_error(batch.error)
+            for message in batch.output:
+                yield message
+
+    async def _wait(self, exec_id: str) -> bytes:
+        # The logic here is similar to how output is read from `exec`
+        output = b""
+        completed = False
+        retries_remaining = 10
+        while not completed:
+            try:
+                async for data in self._consume_output(exec_id):
+                    if data is None:
+                        completed = True
+                        break
+                    output += data
+            except (GRPCError, StreamTerminatedError) as exc:
+                if retries_remaining > 0:
+                    retries_remaining -= 1
+                    if isinstance(exc, GRPCError):
+                        if exc.status in RETRYABLE_GRPC_STATUS_CODES:
+                            await asyncio.sleep(1.0)
+                            continue
+                    elif isinstance(exc, StreamTerminatedError):
+                        continue
+                raise
+        return output
+
+    def _validate_type(self, data: Union[bytes, str]) -> None:
+        if self._binary and isinstance(data, str):
+            raise TypeError("Expected bytes when in binary mode")
+        if not self._binary and isinstance(data, bytes):
+            raise TypeError("Expected str when in text mode")
+
+    async def _open_file(self, path: str, mode: str) -> None:
+        resp = await self._make_request(
+            api_pb2.ContainerFilesystemExecRequest(
+                file_open_request=api_pb2.ContainerFileOpenRequest(path=path, mode=mode),
+                task_id=self._task_id,
+            )
+        )
+        if not resp.HasField("file_descriptor"):
+            raise FilesystemExecutionError("Failed to open file")
+        self._file_descriptor = resp.file_descriptor
+        await self._wait(resp.exec_id)
+
+    @classmethod
+    async def create(
+        cls, path: str, mode: Union["_typeshed.OpenTextMode", "_typeshed.OpenBinaryMode"], client: _Client, task_id: str
+    ) -> "_FileIO":
+        """Create a new FileIO handle."""
+        self = cls.__new__(cls)
+        self._client = client
+        self._task_id = task_id
+        self._validate_mode(mode)
+        await self._open_file(path, mode)
+        self._closed = False
+        return self
+
+    async def _make_request(
+        self, request: api_pb2.ContainerFilesystemExecRequest
+    ) -> api_pb2.ContainerFilesystemExecResponse:
+        assert self._client is not None
+        return await retry_transient_errors(self._client.stub.ContainerFilesystemExec, request)
+
+    async def _make_read_request(self, n: Optional[int]) -> bytes:
+        resp = await self._make_request(
+            api_pb2.ContainerFilesystemExecRequest(
+                file_read_request=api_pb2.ContainerFileReadRequest(file_descriptor=self._file_descriptor, n=n),
+                task_id=self._task_id,
+            )
+        )
+        return await self._wait(resp.exec_id)
+
+    async def read(self, n: Optional[int] = None) -> T:
+        """Read n bytes from the current position, or the entire remaining file if n is None."""
+        self._check_closed()
+        self._check_readable()
+        if n is not None and n > READ_FILE_SIZE_LIMIT:
+            raise ValueError("Read request payload exceeds 100 MiB limit")
+        output = await self._make_read_request(n)
+        if self._binary:
+            return cast(T, output)
+        return cast(T, output.decode("utf-8"))
+
+    async def readline(self) -> T:
+        """Read a single line from the current position."""
+        self._check_closed()
+        self._check_readable()
+        resp = await self._make_request(
+            api_pb2.ContainerFilesystemExecRequest(
+                file_read_line_request=api_pb2.ContainerFileReadLineRequest(file_descriptor=self._file_descriptor),
+                task_id=self._task_id,
+            )
+        )
+        output = await self._wait(resp.exec_id)
+        if self._binary:
+            return cast(T, output)
+        return cast(T, output.decode("utf-8"))
+
+    async def readlines(self) -> Sequence[T]:
+        """Read all lines from the current position."""
+        self._check_closed()
+        self._check_readable()
+        output = await self._make_read_request(None)
+        if self._binary:
+            lines_bytes = output.split(b"\n")
+            output = [line + b"\n" for line in lines_bytes[:-1]] + ([lines_bytes[-1]] if lines_bytes[-1] else [])
+            return cast(Sequence[T], output)
+        else:
+            lines = output.decode("utf-8").split("\n")
+            output = [line + "\n" for line in lines[:-1]] + ([lines[-1]] if lines[-1] else [])
+            return cast(Sequence[T], output)
+
+    async def write(self, data: Union[bytes, str]) -> None:
+        """Write data to the current position.
+
+        Writes may not appear until the entire buffer is flushed, which
+        can be done manually with `flush()` or automatically when the file is
+        closed.
+        """
+        self._check_closed()
+        self._check_writable()
+        self._validate_type(data)
+        if isinstance(data, str):
+            data = data.encode("utf-8")
+        if len(data) > LARGE_FILE_SIZE_LIMIT:
+            raise ValueError("Write request payload exceeds 16 MiB limit")
+        resp = await self._make_request(
+            api_pb2.ContainerFilesystemExecRequest(
+                file_write_request=api_pb2.ContainerFileWriteRequest(file_descriptor=self._file_descriptor, data=data),
+                task_id=self._task_id,
+            )
+        )
+        await self._wait(resp.exec_id)
+
+    async def flush(self) -> None:
+        """Flush the buffer to disk."""
+        self._check_closed()
+        self._check_writable()
+        resp = await self._make_request(
+            api_pb2.ContainerFilesystemExecRequest(
+                file_flush_request=api_pb2.ContainerFileFlushRequest(file_descriptor=self._file_descriptor),
+                task_id=self._task_id,
+            )
+        )
+        await self._wait(resp.exec_id)
+
+    def _get_whence(self, whence: int):
+        if whence == 0:
+            return api_pb2.SeekWhence.SEEK_SET
+        elif whence == 1:
+            return api_pb2.SeekWhence.SEEK_CUR
+        elif whence == 2:
+            return api_pb2.SeekWhence.SEEK_END
+        else:
+            raise ValueError(f"Invalid whence value: {whence}")
+
+    async def seek(self, offset: int, whence: int = 0) -> None:
+        """Move to a new position in the file.
+
+        `whence` defaults to 0 (absolute file positioning); other values are 1
+        (relative to the current position) and 2 (relative to the file's end).
+        """
+        self._check_closed()
+        resp = await self._make_request(
+            api_pb2.ContainerFilesystemExecRequest(
+                file_seek_request=api_pb2.ContainerFileSeekRequest(
+                    file_descriptor=self._file_descriptor,
+                    offset=offset,
+                    whence=self._get_whence(whence),
+                ),
+                task_id=self._task_id,
+            )
+        )
+        await self._wait(resp.exec_id)
+
+    async def _close(self) -> None:
+        # Buffer is flushed by the runner on close
+        resp = await self._make_request(
+            api_pb2.ContainerFilesystemExecRequest(
+                file_close_request=api_pb2.ContainerFileCloseRequest(file_descriptor=self._file_descriptor),
+                task_id=self._task_id,
+            )
+        )
+        self._closed = True
+        await self._wait(resp.exec_id)
+
+    async def close(self) -> None:
+        """Flush the buffer and close the file."""
+        await self._close()
+
+    # also validated in the runner, but checked in the client to catch errors early
+    def _check_writable(self) -> None:
+        if not self._writable:
+            raise io.UnsupportedOperation("not writeable")
+
+    # also validated in the runner, but checked in the client to catch errors early
+    def _check_readable(self) -> None:
+        if not self._readable:
+            raise io.UnsupportedOperation("not readable")
+
+    # also validated in the runner, but checked in the client to catch errors early
+    def _check_closed(self) -> None:
+        if self._closed:
+            raise ValueError("I/O operation on closed file")
+
+    def __enter__(self) -> "_FileIO":
+        self._check_closed()
+        return self
+
+    async def __exit__(self, exc_type, exc_value, traceback) -> None:
+        await self._close()
+
+
+delete_bytes = synchronize_api(_delete_bytes)
+replace_bytes = synchronize_api(_replace_bytes)
+FileIO = synchronize_api(_FileIO)

modal/file_io.pyi

@@ -0,0 +1,185 @@
+import _typeshed
+import modal.client
+import modal_proto.api_pb2
+import typing
+import typing_extensions
+
+T = typing.TypeVar("T")
+
+async def _delete_bytes(
+    file: _FileIO, start: typing.Optional[int] = None, end: typing.Optional[int] = None
+) -> None: ...
+async def _replace_bytes(
+    file: _FileIO, data: bytes, start: typing.Optional[int] = None, end: typing.Optional[int] = None
+) -> None: ...
+
+class _FileIO(typing.Generic[T]):
+    _task_id: str
+    _file_descriptor: str
+    _client: typing.Optional[modal.client._Client]
+
+    def _validate_mode(self, mode: str) -> None: ...
+    def _handle_error(self, error: modal_proto.api_pb2.SystemErrorMessage) -> None: ...
+    def _consume_output(self, exec_id: str) -> typing.AsyncIterator[typing.Optional[bytes]]: ...
+    async def _wait(self, exec_id: str) -> bytes: ...
+    def _validate_type(self, data: typing.Union[bytes, str]) -> None: ...
+    async def _open_file(self, path: str, mode: str) -> None: ...
+    @classmethod
+    async def create(
+        cls,
+        path: str,
+        mode: typing.Union[_typeshed.OpenTextMode, _typeshed.OpenBinaryMode],
+        client: modal.client._Client,
+        task_id: str,
+    ) -> _FileIO: ...
+    async def _make_request(
+        self, request: modal_proto.api_pb2.ContainerFilesystemExecRequest
+    ) -> modal_proto.api_pb2.ContainerFilesystemExecResponse: ...
+    async def _make_read_request(self, n: typing.Optional[int]) -> bytes: ...
+    async def read(self, n: typing.Optional[int] = None) -> T: ...
+    async def readline(self) -> T: ...
+    async def readlines(self) -> typing.Sequence[T]: ...
+    async def write(self, data: typing.Union[bytes, str]) -> None: ...
+    async def flush(self) -> None: ...
+    def _get_whence(self, whence: int): ...
+    async def seek(self, offset: int, whence: int = 0) -> None: ...
+    async def _close(self) -> None: ...
+    async def close(self) -> None: ...
+    def _check_writable(self) -> None: ...
+    def _check_readable(self) -> None: ...
+    def _check_closed(self) -> None: ...
+    def __enter__(self) -> _FileIO: ...
+    async def __exit__(self, exc_type, exc_value, traceback) -> None: ...
+
+class __delete_bytes_spec(typing_extensions.Protocol):
+    def __call__(self, file: FileIO, start: typing.Optional[int] = None, end: typing.Optional[int] = None) -> None: ...
+    async def aio(self, file: FileIO, start: typing.Optional[int] = None, end: typing.Optional[int] = None) -> None: ...
+
+delete_bytes: __delete_bytes_spec
+
+class __replace_bytes_spec(typing_extensions.Protocol):
+    def __call__(
+        self, file: FileIO, data: bytes, start: typing.Optional[int] = None, end: typing.Optional[int] = None
+    ) -> None: ...
+    async def aio(
+        self, file: FileIO, data: bytes, start: typing.Optional[int] = None, end: typing.Optional[int] = None
+    ) -> None: ...
+
+replace_bytes: __replace_bytes_spec
+
+T_INNER = typing.TypeVar("T_INNER", covariant=True)
+
+class FileIO(typing.Generic[T]):
+    _task_id: str
+    _file_descriptor: str
+    _client: typing.Optional[modal.client.Client]
+
+    def __init__(self, /, *args, **kwargs): ...
+    def _validate_mode(self, mode: str) -> None: ...
+    def _handle_error(self, error: modal_proto.api_pb2.SystemErrorMessage) -> None: ...
+
+    class ___consume_output_spec(typing_extensions.Protocol):
+        def __call__(self, exec_id: str) -> typing.Iterator[typing.Optional[bytes]]: ...
+        def aio(self, exec_id: str) -> typing.AsyncIterator[typing.Optional[bytes]]: ...
+
+    _consume_output: ___consume_output_spec
+
+    class ___wait_spec(typing_extensions.Protocol):
+        def __call__(self, exec_id: str) -> bytes: ...
+        async def aio(self, exec_id: str) -> bytes: ...
+
+    _wait: ___wait_spec
+
+    def _validate_type(self, data: typing.Union[bytes, str]) -> None: ...
+
+    class ___open_file_spec(typing_extensions.Protocol):
+        def __call__(self, path: str, mode: str) -> None: ...
+        async def aio(self, path: str, mode: str) -> None: ...
+
+    _open_file: ___open_file_spec
+
+    @classmethod
+    def create(
+        cls,
+        path: str,
+        mode: typing.Union[_typeshed.OpenTextMode, _typeshed.OpenBinaryMode],
+        client: modal.client.Client,
+        task_id: str,
+    ) -> FileIO: ...
+
+    class ___make_request_spec(typing_extensions.Protocol):
+        def __call__(
+            self, request: modal_proto.api_pb2.ContainerFilesystemExecRequest
+        ) -> modal_proto.api_pb2.ContainerFilesystemExecResponse: ...
+        async def aio(
+            self, request: modal_proto.api_pb2.ContainerFilesystemExecRequest
+        ) -> modal_proto.api_pb2.ContainerFilesystemExecResponse: ...
+
+    _make_request: ___make_request_spec
+
+    class ___make_read_request_spec(typing_extensions.Protocol):
+        def __call__(self, n: typing.Optional[int]) -> bytes: ...
+        async def aio(self, n: typing.Optional[int]) -> bytes: ...
+
+    _make_read_request: ___make_read_request_spec
+
+    class __read_spec(typing_extensions.Protocol[T_INNER]):
+        def __call__(self, n: typing.Optional[int] = None) -> T_INNER: ...
+        async def aio(self, n: typing.Optional[int] = None) -> T_INNER: ...
+
+    read: __read_spec[T]
+
+    class __readline_spec(typing_extensions.Protocol[T_INNER]):
+        def __call__(self) -> T_INNER: ...
+        async def aio(self) -> T_INNER: ...
+
+    readline: __readline_spec[T]
+
+    class __readlines_spec(typing_extensions.Protocol[T_INNER]):
+        def __call__(self) -> typing.Sequence[T_INNER]: ...
+        async def aio(self) -> typing.Sequence[T_INNER]: ...
+
+    readlines: __readlines_spec[T]
+
+    class __write_spec(typing_extensions.Protocol):
+        def __call__(self, data: typing.Union[bytes, str]) -> None: ...
+        async def aio(self, data: typing.Union[bytes, str]) -> None: ...
+
+    write: __write_spec
+
+    class __flush_spec(typing_extensions.Protocol):
+        def __call__(self) -> None: ...
+        async def aio(self) -> None: ...
+
+    flush: __flush_spec
+
+    def _get_whence(self, whence: int): ...
+
+    class __seek_spec(typing_extensions.Protocol):
+        def __call__(self, offset: int, whence: int = 0) -> None: ...
+        async def aio(self, offset: int, whence: int = 0) -> None: ...
+
+    seek: __seek_spec
+
+    class ___close_spec(typing_extensions.Protocol):
+        def __call__(self) -> None: ...
+        async def aio(self) -> None: ...
+
+    _close: ___close_spec
+
+    class __close_spec(typing_extensions.Protocol):
+        def __call__(self) -> None: ...
+        async def aio(self) -> None: ...
+
+    close: __close_spec
+
+    def _check_writable(self) -> None: ...
+    def _check_readable(self) -> None: ...
+    def _check_closed(self) -> None: ...
+    def __enter__(self) -> FileIO: ...
+
+    class ____exit___spec(typing_extensions.Protocol):
+        def __call__(self, exc_type, exc_value, traceback) -> None: ...
+        async def aio(self, exc_type, exc_value, traceback) -> None: ...
+
+    __exit__: ____exit___spec

modal/functions.pyi

@@ -455,11 +455,11 @@ class Function(typing.Generic[P, ReturnType, OriginalReturnType], modal.object.O
 
     _call_generator_nowait: ___call_generator_nowait_spec
 
-    class __remote_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
+    class __remote_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
         def __call__(self, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> ReturnType_INNER: ...
         async def aio(self, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> ReturnType_INNER: ...
 
-    remote: __remote_spec[ReturnType, P]
+    remote: __remote_spec[P, ReturnType]
 
     class __remote_gen_spec(typing_extensions.Protocol):
         def __call__(self, *args, **kwargs) -> typing.Generator[typing.Any, None, None]: ...
@@ -471,17 +471,17 @@ class Function(typing.Generic[P, ReturnType, OriginalReturnType], modal.object.O
     def _get_obj(self) -> typing.Optional[modal.cls.Obj]: ...
     def local(self, *args: P.args, **kwargs: P.kwargs) -> OriginalReturnType: ...
 
-    class ___experimental_spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
+    class ___experimental_spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
         def __call__(self, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]: ...
         async def aio(self, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]: ...
 
-    _experimental_spawn: ___experimental_spawn_spec[ReturnType, P]
+    _experimental_spawn: ___experimental_spawn_spec[P, ReturnType]
 
-    class __spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
+    class __spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
         def __call__(self, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]: ...
         async def aio(self, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]: ...
 
-    spawn: __spawn_spec[ReturnType, P]
+    spawn: __spawn_spec[P, ReturnType]
 
     def get_raw_f(self) -> typing.Callable[..., typing.Any]: ...
 

modal/sandbox.py

@@ -4,6 +4,9 @@ import os
 from collections.abc import AsyncGenerator, Sequence
 from typing import TYPE_CHECKING, Literal, Optional, Union, overload
 
+if TYPE_CHECKING:
+    import _typeshed
+
 from google.protobuf.message import Message
 from grpclib import GRPCError, Status
 
@@ -29,6 +32,7 @@ from .exception import (
     deprecation_error,
     deprecation_warning,
 )
+from .file_io import _FileIO
 from .gpu import GPU_T
 from .image import _Image
 from .io_streams import StreamReader, StreamWriter, _StreamReader, _StreamWriter
@@ -527,6 +531,42 @@ class _Sandbox(_Object, type_prefix="sb"):
         by_line = bufsize == 1
         return _ContainerProcess(resp.exec_id, self._client, stdout=stdout, stderr=stderr, text=text, by_line=by_line)
 
+    @overload
+    async def open(
+        self,
+        path: str,
+        mode: "_typeshed.OpenTextMode",
+    ) -> _FileIO[str]:
+        ...
+
+    @overload
+    async def open(
+        self,
+        path: str,
+        mode: "_typeshed.OpenBinaryMode",
+    ) -> _FileIO[bytes]:
+        ...
+
+    async def open(
+        self,
+        path: str,
+        mode: Union["_typeshed.OpenTextMode", "_typeshed.OpenBinaryMode"] = "r",
+    ):
+        """Open a file in the Sandbox and return
+        a [`FileIO`](/docs/reference/modal.FileIO#modalfile_io) handle.
+
+        **Usage**
+
+        ```python notest
+        sb = modal.Sandbox.create(app=sb_app)
+        f = sb.open("/test.txt", "w")
+        f.write("hello")
+        f.close()
+        ```
+        """
+        task_id = await self._get_task_id()
+        return await _FileIO.create(path, mode, self._client, task_id)
+
     @property
     def stdout(self) -> _StreamReader[str]:
         """

modal/sandbox.pyi

@@ -1,3 +1,4 @@
+import _typeshed
 import collections.abc
 import google.protobuf.message
 import modal._tunnel
@@ -5,6 +6,7 @@ import modal.app
 import modal.client
 import modal.cloud_bucket_mount
 import modal.container_process
+import modal.file_io
 import modal.gpu
 import modal.image
 import modal.io_streams
@@ -122,6 +124,10 @@ class _Sandbox(modal.object._Object):
         bufsize: typing.Literal[-1, 1] = -1,
         _pty_info: typing.Optional[modal_proto.api_pb2.PTYInfo] = None,
     ) -> modal.container_process._ContainerProcess[bytes]: ...
+    @typing.overload
+    async def open(self, path: str, mode: _typeshed.OpenTextMode) -> modal.file_io._FileIO[str]: ...
+    @typing.overload
+    async def open(self, path: str, mode: _typeshed.OpenBinaryMode) -> modal.file_io._FileIO[bytes]: ...
     @property
     def stdout(self) -> modal.io_streams._StreamReader[str]: ...
     @property
@@ -349,6 +355,18 @@ class Sandbox(modal.object.Object):
 
     exec: __exec_spec
 
+    class __open_spec(typing_extensions.Protocol):
+        @typing.overload
+        def __call__(self, path: str, mode: _typeshed.OpenTextMode) -> modal.file_io.FileIO[str]: ...
+        @typing.overload
+        def __call__(self, path: str, mode: _typeshed.OpenBinaryMode) -> modal.file_io.FileIO[bytes]: ...
+        @typing.overload
+        async def aio(self, path: str, mode: _typeshed.OpenTextMode) -> modal.file_io.FileIO[str]: ...
+        @typing.overload
+        async def aio(self, path: str, mode: _typeshed.OpenBinaryMode) -> modal.file_io.FileIO[bytes]: ...
+
+    open: __open_spec
+
     @property
     def stdout(self) -> modal.io_streams.StreamReader[str]: ...
     @property

{modal-0.68.1.dist-info → modal-0.68.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: modal
-Version: 0.68.1
+Version: 0.68.2
 Summary: Python client library for Modal
 Author: Modal Labs
 Author-email: support@modal.com
@@ -21,7 +21,7 @@ Requires-Dist: fastapi
 Requires-Dist: grpclib (==0.4.7)
 Requires-Dist: protobuf (!=4.24.0,<6.0,>=3.19)
 Requires-Dist: rich (>=12.0.0)
-Requires-Dist: synchronicity (~=0.9.4)
+Requires-Dist: synchronicity (~=0.9.6)
 Requires-Dist: toml
 Requires-Dist: typer (>=0.9)
 Requires-Dist: types-certifi

{modal-0.68.1.dist-info → modal-0.68.2.dist-info}/RECORD

@@ -19,7 +19,7 @@ modal/app.py,sha256=EJ7FUN6rWnSwLJoYJh8nmKg_t-8hdN8_rt0OrkP7JvQ,46084
 modal/app.pyi,sha256=BE5SlR5tRECuc6-e2lUuOknDdov3zxgZ4N0AsLb5ZVQ,25270
 modal/call_graph.py,sha256=1g2DGcMIJvRy-xKicuf63IVE98gJSnQsr8R_NVMptNc,2581
 modal/client.py,sha256=uy1Lw3hipt9ILv19VdmBBGYIW7VHmr4rzXi7pO7Kg7s,15791
-modal/client.pyi,sha256=Mpm_iZr5M6GeCM_Dey5sDQtDM0T-2mppR9-n15iBr0Q,7352
+modal/client.pyi,sha256=HARg2kCIdOYmjEulbyyZJAN3F01iJPF8IiBZbqlcEFk,7352
 modal/cloud_bucket_mount.py,sha256=G7T7jWLD0QkmrfKR75mSTwdUZ2xNfj7pkVqb4ipmxmI,5735
 modal/cloud_bucket_mount.pyi,sha256=CEi7vrH3kDUF4LAy4qP6tfImy2UJuFRcRbsgRNM1wo8,1403
 modal/cls.py,sha256=pMirIOmb59YzaIK2rn7Vd756E1QKDDweYT90GYIHiMk,27472
@@ -31,10 +31,12 @@ modal/dict.py,sha256=RmJlEwFJOdSfAYcVa50hbbFccV8e7BvC5tc5g1HXF-c,12622
 modal/dict.pyi,sha256=2cYgOqBxYZih4BYgMV0c3rNPuxYR6-cB1GBXzFkHA5c,7265
 modal/environments.py,sha256=5cgA-zbm6ngKLsRA19zSOgtgo9-BarJK3FJK0BiF2Lo,6505
 modal/environments.pyi,sha256=XalNpiPkAtHWAvOU2Cotq0ozmtl-Jv0FDsR8h9mr27Q,3521
-modal/exception.py,sha256=eSQZ0u1z-RPMW9x6AGMySi-LWyqkTtjZM-RnvhyfWWQ,6997
+modal/exception.py,sha256=dRK789TD1HaB63kHhu1yZuvS2vP_Vua3iLMBtA6dgqk,7128
 modal/experimental.py,sha256=jFuNbwrNHos47viMB9q-cHJSvf2RDxDdoEcss9plaZE,2302
+modal/file_io.py,sha256=q8s872qf6Ntdw7dPogDlpYbixxGkwCA0BlQn2UUoVhY,14637
+modal/file_io.pyi,sha256=pfkmJiaBpMCZReE6-KCjYOzB1dVtyYDYokJoYX8ARK4,6932
 modal/functions.py,sha256=Z2g1CuDTz_491ReOJKs66qGlodPDpKAiKHVwARL2zYA,66792
-modal/functions.pyi,sha256=4k5CaJ9iTuEyHQ2rC5OysNHBLv1CZrD7zBMU1zXIU4w,24988
+modal/functions.pyi,sha256=IyuM9TV79JfrtfTaJ4yq3EcWp3yHuxLavpxTOwSWEDw,24988
 modal/gpu.py,sha256=r4rL6uH3UJIQthzYvfWauXNyh01WqCPtKZCmmSX1fd4,6881
 modal/image.py,sha256=cQ6WP1xHXZT_nY8z3aEFiGwKzrTV0yxi3Ab8JzF91eo,79653
 modal/image.pyi,sha256=PIKH6JBA4L5TfdJrQu3pm2ykyIITmiP920TpP8cdyQA,24585
@@ -60,8 +62,8 @@ modal/retries.py,sha256=HKR2Q9aNPWkMjQ5nwobqYTuZaSuw0a8lI2zrtY5IW98,5230
 modal/runner.py,sha256=Q02VdfLCO7YKpnOSqqh58XL3hR2XHaDeiJVYW3MKz_8,24580
 modal/runner.pyi,sha256=BvMS1ZVzWSn8B8q0KnIZOJKPkN5L-i5b-USbV6SWWHQ,5177
 modal/running_app.py,sha256=CshNvGDJtagOdKW54uYjY8HY73j2TpnsL9jkPFZAsfA,560
-modal/sandbox.py,sha256=Yd__KipEINH2euDPOcm5MPBnagRv19Sa5z5tJCvGOQs,26360
-modal/sandbox.pyi,sha256=fRl32Pt5F6TbK7aYewjlcL4WQxxmp7m6Ybktmkd2VOk,18108
+modal/sandbox.py,sha256=abmprnPtA-WVsHKu4J1deoltpAUvXtIHQHX-ZpYjYPE,27293
+modal/sandbox.pyi,sha256=QPNuiTLNoKwYf8JK_fmfUBXpdGYlukyaksFV1DpCd2g,18987
 modal/schedule.py,sha256=0ZFpKs1bOxeo5n3HZjoL7OE2ktsb-_oGtq-WJEPO4tY,2615
 modal/scheduler_placement.py,sha256=BAREdOY5HzHpzSBqt6jDVR6YC_jYfHMVqOzkyqQfngU,1235
 modal/secret.py,sha256=Y1WgybQIkfkxdzH9CQ1h-Wd1DJJpzipigMhyyvSxTww,10007
@@ -131,7 +133,7 @@ modal/requirements/README.md,sha256=9tK76KP0Uph7O0M5oUgsSwEZDj5y-dcUPsnpR0Sc-Ik,
 modal/requirements/base-images.json,sha256=kLNo5Sqmnhp9H6Hr9IcaGJFrRaRg1yfuepUWkm-y8iQ,571
 modal_docs/__init__.py,sha256=svYKtV8HDwDCN86zbdWqyq5T8sMdGDj0PVlzc2tIxDM,28
 modal_docs/gen_cli_docs.py,sha256=c1yfBS_x--gL5bs0N4ihMwqwX8l3IBWSkBAKNNIi6bQ,3801
-modal_docs/gen_reference_docs.py,sha256=AI8h-JKfwn7Tohm3P3D5G0SivSpdGgN6gnw-fED-S0s,6613
+modal_docs/gen_reference_docs.py,sha256=aDcUSSDtAAZ4eeFWyroeIg2TOzyRoYcic-d9Zh9TdLY,6656
 modal_docs/mdmd/__init__.py,sha256=svYKtV8HDwDCN86zbdWqyq5T8sMdGDj0PVlzc2tIxDM,28
 modal_docs/mdmd/mdmd.py,sha256=F6EXKkjwrTbOiG6I7wKtNGVVmmeWLAJ5pnE7DUkDpvM,6231
 modal_docs/mdmd/signatures.py,sha256=XJaZrK7Mdepk5fdX51A8uENiLFNil85Ud0d4MH8H5f0,3218
@@ -159,10 +161,10 @@ modal_proto/options_pb2_grpc.pyi,sha256=CImmhxHsYnF09iENPoe8S4J-n93jtgUYD2JPAc0y
 modal_proto/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 modal_version/__init__.py,sha256=RT6zPoOdFO99u5Wcxxaoir4ZCuPTbQ22cvzFAXl3vUY,470
 modal_version/__main__.py,sha256=2FO0yYQQwDTh6udt1h-cBnGd1c4ZyHnHSI4BksxzVac,105
-modal_version/_version_generated.py,sha256=WCQ6ahtgY9jKjpnPehIAR2jb6JCAyY8f-a6ORy1yMZE,148
-modal-0.68.1.dist-info/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
-modal-0.68.1.dist-info/METADATA,sha256=ZRM5JqpOFrRmhBWuNm2S4AkEL1IaWjJi8xpbnLfl6hI,2328
-modal-0.68.1.dist-info/WHEEL,sha256=G16H4A3IeoQmnOrYV4ueZGKSjhipXx8zc8nu9FGlvMA,92
-modal-0.68.1.dist-info/entry_points.txt,sha256=An-wYgeEUnm6xzrAP9_NTSTSciYvvEWsMZILtYrvpAI,46
-modal-0.68.1.dist-info/top_level.txt,sha256=1nvYbOSIKcmU50fNrpnQnrrOpj269ei3LzgB6j9xGqg,64
-modal-0.68.1.dist-info/RECORD,,
+modal_version/_version_generated.py,sha256=6Pvpcc5MvVX_YgJS7zOEdJe-DbGK8uv3kqiGt-OVVXE,148
+modal-0.68.2.dist-info/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
+modal-0.68.2.dist-info/METADATA,sha256=5nS06eizxvISwpNNTho3610CO0mCCjpisIfo5STyfYY,2328
+modal-0.68.2.dist-info/WHEEL,sha256=G16H4A3IeoQmnOrYV4ueZGKSjhipXx8zc8nu9FGlvMA,92
+modal-0.68.2.dist-info/entry_points.txt,sha256=An-wYgeEUnm6xzrAP9_NTSTSciYvvEWsMZILtYrvpAI,46
+modal-0.68.2.dist-info/top_level.txt,sha256=1nvYbOSIKcmU50fNrpnQnrrOpj269ei3LzgB6j9xGqg,64
+modal-0.68.2.dist-info/RECORD,,

modal_docs/gen_reference_docs.py

@@ -86,6 +86,7 @@ def run(output_dir: str = None):
         ("modal.Sandbox", "modal.sandbox"),
         ("modal.ContainerProcess", "modal.container_process"),
         ("modal.io_streams", "modal.io_streams"),
+        ("modal.FileIO", "modal.file_io"),
     ]
     # These aren't defined in `modal`, but should still be documented as top-level entries.
     forced_members = {"web_endpoint", "asgi_app", "method", "wsgi_app", "forward"}

modal_version/_version_generated.py

@@ -1,4 +1,4 @@
 # Copyright Modal Labs 2024
 
 # Note: Reset this value to -1 whenever you make a minor `0.X` release of the client.
-build_number = 1  # git: a723471
+build_number = 2  # git: bf9e3ce