modal 1.2.1.dev11__py3-none-any.whl → 1.2.1.dev13__py3-none-any.whl

modal/client.pyi

@@ -33,7 +33,7 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.2.1.dev11",
+        version: str = "1.2.1.dev13",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.
@@ -164,7 +164,7 @@ class Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.2.1.dev11",
+        version: str = "1.2.1.dev13",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.

modal/container_process.py

@@ -155,8 +155,16 @@ class _ContainerProcess(Generic[T]):
         on_connect = asyncio.Event()
 
         async def _write_to_fd_loop(stream: _StreamReader):
+            # This is required to make modal shell to an existing task work,
+            # since that uses ContainerExec RPCs directly, but this is hacky.
+            #
+            # TODO(saltzm): Once we use the new exec path for that use case, this code can all be removed.
+            from .io_streams import _StreamReaderThroughServer
+
+            assert isinstance(stream._impl, _StreamReaderThroughServer)
+            stream_impl = stream._impl
             # Don't skip empty messages so we can detect when the process has booted.
-            async for chunk in stream._get_logs(skip_empty_messages=False):
+            async for chunk in stream_impl._get_logs(skip_empty_messages=False):
                 if chunk is None:
                     break
 

modal/io_streams.py

@@ -1,7 +1,9 @@
 # Copyright Modal Labs 2022
 import asyncio
+import codecs
 import time
 from collections.abc import AsyncGenerator, AsyncIterator
+from dataclasses import dataclass
 from typing import (
     TYPE_CHECKING,
     Generic,
@@ -15,11 +17,12 @@ from typing import (
 from grpclib import Status
 from grpclib.exceptions import GRPCError, StreamTerminatedError
 
-from modal.exception import ClientClosed, InvalidError
+from modal.exception import ClientClosed, ExecTimeoutError, InvalidError
 from modal_proto import api_pb2
 
 from ._utils.async_utils import synchronize_api
 from ._utils.grpc_utils import RETRYABLE_GRPC_STATUS_CODES, retry_transient_errors
+from ._utils.task_command_router_client import TaskCommandRouterClient
 from .client import _Client
 from .config import logger
 from .stream_type import StreamType
@@ -83,27 +86,8 @@ async def _container_process_logs_iterator(
 T = TypeVar("T", str, bytes)
 
 
-class _StreamReader(Generic[T]):
-    """Retrieve logs from a stream (`stdout` or `stderr`).
-
-    As an asynchronous iterable, the object supports the `for` and `async for`
-    statements. Just loop over the object to read in chunks.
-
-    **Usage**
-
-    ```python fixture:running_app
-    from modal import Sandbox
-
-    sandbox = Sandbox.create(
-        "bash",
-        "-c",
-        "for i in $(seq 1 10); do echo foo; sleep 0.1; done",
-        app=running_app,
-    )
-    for message in sandbox.stdout:
-        print(f"Message: {message}")
-    ```
-    """
+class _StreamReaderThroughServer(Generic[T]):
+    """A StreamReader implementation that reads from the server."""
 
     _stream: Optional[AsyncGenerator[Optional[bytes], None]]
 
@@ -133,10 +117,6 @@ class _StreamReader(Generic[T]):
         if object_type == "sandbox" and not text:
             raise ValueError("Sandbox streams must have text mode enabled.")
 
-        # line-buffering is only supported when text=True
-        if by_line and not text:
-            raise ValueError("line-buffering is only supported when text=True")
-
         self._text = text
         self._by_line = by_line
 
@@ -166,19 +146,7 @@ class _StreamReader(Generic[T]):
         return self._file_descriptor
 
     async def read(self) -> T:
-        """Fetch the entire contents of the stream until EOF.
-
-        **Usage**
-
-        ```python fixture:running_app
-        from modal import Sandbox
-
-        sandbox = Sandbox.create("echo", "hello", app=running_app)
-        sandbox.wait()
-
-        print(sandbox.stdout.read())
-        ```
-        """
+        """Fetch the entire contents of the stream until EOF."""
         data_str = ""
         data_bytes = b""
         logger.debug(f"{self._object_id} StreamReader fd={self._file_descriptor} read starting")
@@ -330,11 +298,6 @@ class _StreamReader(Generic[T]):
                 self._stream = self._get_logs()
         return self._stream
 
-    def __aiter__(self) -> AsyncIterator[T]:
-        """mdmd:hidden"""
-        self._ensure_stream()
-        return self
-
     async def __anext__(self) -> T:
         """mdmd:hidden"""
         stream = self._ensure_stream()
@@ -356,10 +319,293 @@ class _StreamReader(Generic[T]):
             await self._stream.aclose()
 
 
+async def _decode_bytes_stream_to_str(stream: AsyncGenerator[bytes, None]) -> AsyncGenerator[str, None]:
+    """Incrementally decode a bytes async generator as UTF-8 without breaking on chunk boundaries.
+
+    This function uses a streaming UTF-8 decoder so that multi-byte characters split across
+    chunks are handled correctly instead of raising ``UnicodeDecodeError``.
+    """
+    decoder = codecs.getincrementaldecoder("utf-8")(errors="strict")
+    async for item in stream:
+        text = decoder.decode(item, final=False)
+        if text:
+            yield text
+    # Flush any buffered partial character at end-of-stream
+    tail = decoder.decode(b"", final=True)
+    if tail:
+        yield tail
+
+
+async def _stream_by_line(stream: AsyncGenerator[bytes, None]) -> AsyncGenerator[bytes, None]:
+    """Yield complete lines only (ending with \n), buffering partial lines until complete."""
+    line_buffer = b""
+    async for message in stream:
+        assert isinstance(message, bytes)
+        line_buffer += message
+        while b"\n" in line_buffer:
+            line, line_buffer = line_buffer.split(b"\n", 1)
+            yield line + b"\n"
+
+    if line_buffer:
+        yield line_buffer
+
+
+@dataclass
+class _StreamReaderThroughCommandRouterParams:
+    file_descriptor: "api_pb2.FileDescriptor.ValueType"
+    task_id: str
+    object_id: str
+    command_router_client: TaskCommandRouterClient
+    deadline: Optional[float]
+
+
+async def _stdio_stream_from_command_router(
+    params: _StreamReaderThroughCommandRouterParams,
+) -> AsyncGenerator[bytes, None]:
+    """Stream raw bytes from the router client."""
+    stream = params.command_router_client.exec_stdio_read(
+        params.task_id, params.object_id, params.file_descriptor, params.deadline
+    )
+    try:
+        async for item in stream:
+            if len(item.data) == 0:
+                # This is an error.
+                raise ValueError("Received empty message streaming stdio from sandbox.")
+
+            yield item.data
+    except ExecTimeoutError:
+        logger.debug(f"Deadline exceeded while streaming stdio for exec {params.object_id}")
+        # TODO(saltzm): This is a weird API, but customers currently may rely on it. We
+        # should probably raise this error rather than just ending the stream.
+        return
+
+
+class _BytesStreamReaderThroughCommandRouter(Generic[T]):
+    """
+    StreamReader implementation that will read directly from the worker that
+    hosts the sandbox.
+
+    This implementation is used for non-text streams.
+    """
+
+    def __init__(
+        self,
+        params: _StreamReaderThroughCommandRouterParams,
+    ) -> None:
+        self._params = params
+        self._stream = None
+
+    @property
+    def file_descriptor(self) -> int:
+        return self._params.file_descriptor
+
+    async def read(self) -> T:
+        data_bytes = b""
+        async for part in self:
+            data_bytes += cast(bytes, part)
+        return cast(T, data_bytes)
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        return self
+
+    async def __anext__(self) -> T:
+        if self._stream is None:
+            self._stream = _stdio_stream_from_command_router(self._params)
+        # This raises StopAsyncIteration if the stream is at EOF.
+        return cast(T, await self._stream.__anext__())
+
+    async def aclose(self):
+        if self._stream:
+            await self._stream.aclose()
+
+
+class _TextStreamReaderThroughCommandRouter(Generic[T]):
+    """
+    StreamReader implementation that will read directly from the worker
+    that hosts the sandbox.
+
+    This implementation is used for text streams.
+    """
+
+    def __init__(
+        self,
+        params: _StreamReaderThroughCommandRouterParams,
+        by_line: bool,
+    ) -> None:
+        self._params = params
+        self._by_line = by_line
+        self._stream = None
+
+    @property
+    def file_descriptor(self) -> int:
+        return self._params.file_descriptor
+
+    async def read(self) -> T:
+        data_str = ""
+        async for part in self:
+            data_str += cast(str, part)
+        return cast(T, data_str)
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        return self
+
+    async def __anext__(self) -> T:
+        if self._stream is None:
+            bytes_stream = _stdio_stream_from_command_router(self._params)
+            if self._by_line:
+                self._stream = _decode_bytes_stream_to_str(_stream_by_line(bytes_stream))
+            else:
+                self._stream = _decode_bytes_stream_to_str(bytes_stream)
+        # This raises StopAsyncIteration if the stream is at EOF.
+        return cast(T, await self._stream.__anext__())
+
+    async def aclose(self):
+        if self._stream:
+            await self._stream.aclose()
+
+
+class _DevnullStreamReader(Generic[T]):
+    """StreamReader implementation for a stream configured with
+    StreamType.DEVNULL. Throws an error if read or any other method is
+    called.
+    """
+
+    def __init__(self, file_descriptor: "api_pb2.FileDescriptor.ValueType") -> None:
+        self._file_descriptor = file_descriptor
+
+    @property
+    def file_descriptor(self) -> int:
+        return self._file_descriptor
+
+    async def read(self) -> T:
+        raise ValueError("read is not supported for a stream configured with StreamType.DEVNULL")
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        raise ValueError("__aiter__ is not supported for a stream configured with StreamType.DEVNULL")
+
+    async def __anext__(self) -> T:
+        raise ValueError("__anext__ is not supported for a stream configured with StreamType.DEVNULL")
+
+    async def aclose(self):
+        raise ValueError("aclose is not supported for a stream configured with StreamType.DEVNULL")
+
+
+class _StreamReader(Generic[T]):
+    """Retrieve logs from a stream (`stdout` or `stderr`).
+
+    As an asynchronous iterable, the object supports the `for` and `async for`
+    statements. Just loop over the object to read in chunks.
+
+    **Usage**
+
+    ```python fixture:running_app
+    from modal import Sandbox
+
+    sandbox = Sandbox.create(
+        "bash",
+        "-c",
+        "for i in $(seq 1 10); do echo foo; sleep 0.1; done",
+        app=running_app,
+    )
+    for message in sandbox.stdout:
+        print(f"Message: {message}")
+    ```
+    """
+
+    def __init__(
+        self,
+        file_descriptor: "api_pb2.FileDescriptor.ValueType",
+        object_id: str,
+        object_type: Literal["sandbox", "container_process"],
+        client: _Client,
+        stream_type: StreamType = StreamType.PIPE,
+        text: bool = True,
+        by_line: bool = False,
+        deadline: Optional[float] = None,
+        command_router_client: Optional[TaskCommandRouterClient] = None,
+        task_id: Optional[str] = None,
+    ) -> None:
+        """mdmd:hidden"""
+        if by_line and not text:
+            raise ValueError("line-buffering is only supported when text=True")
+
+        if command_router_client is None:
+            self._impl = _StreamReaderThroughServer(
+                file_descriptor, object_id, object_type, client, stream_type, text, by_line, deadline
+            )
+        else:
+            # The only reason task_id is optional is because StreamReader is
+            # also used for sandbox logs, which don't have a task ID available
+            # when the StreamReader is created.
+            assert task_id is not None
+            assert object_type == "container_process"
+            if stream_type == StreamType.DEVNULL:
+                self._impl = _DevnullStreamReader(file_descriptor)
+            else:
+                assert stream_type == StreamType.PIPE or stream_type == StreamType.STDOUT
+                # TODO(saltzm): The original implementation of STDOUT StreamType in
+                # _StreamReaderThroughServer prints to stdout immediately. This doesn't match
+                # python subprocess.run, which uses None to print to stdout immediately, and uses
+                # STDOUT as an argument to stderr to redirect stderr to the stdout stream. We should
+                # implement the old behavior here before moving out of beta, but after that
+                # we should consider changing the API to match python subprocess.run. I don't expect
+                # many customers are using this in any case, so I think it's fine to leave this
+                # unimplemented for now.
+                if stream_type == StreamType.STDOUT:
+                    raise NotImplementedError(
+                        "Currently only the PIPE stream type is supported when using exec "
+                        "through a task command router, which is currently in beta."
+                    )
+                params = _StreamReaderThroughCommandRouterParams(
+                    file_descriptor, task_id, object_id, command_router_client, deadline
+                )
+                if text:
+                    self._impl = _TextStreamReaderThroughCommandRouter(params, by_line)
+                else:
+                    self._impl = _BytesStreamReaderThroughCommandRouter(params)
+
+    @property
+    def file_descriptor(self) -> int:
+        """Possible values are `1` for stdout and `2` for stderr."""
+        return self._impl.file_descriptor
+
+    async def read(self) -> T:
+        """Fetch the entire contents of the stream until EOF.
+
+        **Usage**
+
+        ```python fixture:running_app
+        from modal import Sandbox
+
+        sandbox = Sandbox.create("echo", "hello", app=running_app)
+        sandbox.wait()
+
+        print(sandbox.stdout.read())
+        ```
+        """
+        return await self._impl.read()
+
+    # TODO(saltzm): I'd prefer to have the implementation classes only implement __aiter__
+    # and have them return generator functions directly, but synchronicity doesn't let us
+    # return self._impl.__aiter__() here because it won't properly wrap the implementation
+    # classes.
+    def __aiter__(self) -> AsyncIterator[T]:
+        """mdmd:hidden"""
+        return self
+
+    async def __anext__(self) -> T:
+        """mdmd:hidden"""
+        return await self._impl.__anext__()
+
+    async def aclose(self):
+        """mdmd:hidden"""
+        await self._impl.aclose()
+
+
 MAX_BUFFER_SIZE = 2 * 1024 * 1024
 
 
-class _StreamWriter:
+class _StreamWriterThroughServer:
     """Provides an interface to buffer and write logs to a sandbox or container process stream (`stdin`)."""
 
     def __init__(self, object_id: str, object_type: Literal["sandbox", "container_process"], client: _Client) -> None:
@@ -381,25 +627,6 @@ class _StreamWriter:
 
         This is non-blocking and queues the data to an internal buffer. Must be
         used along with the `drain()` method, which flushes the buffer.
-
-        **Usage**
-
-        ```python fixture:running_app
-        from modal import Sandbox
-
-        sandbox = Sandbox.create(
-            "bash",
-            "-c",
-            "while read line; do echo $line; done",
-            app=running_app,
-        )
-        sandbox.stdin.write(b"foo\\n")
-        sandbox.stdin.write(b"bar\\n")
-        sandbox.stdin.write_eof()
-
-        sandbox.stdin.drain()
-        sandbox.wait()
-        ```
         """
         if self._is_closed:
             raise ValueError("Stdin is closed. Cannot write to it.")
@@ -407,7 +634,7 @@ class _StreamWriter:
             if isinstance(data, str):
                 data = data.encode("utf-8")
             if len(self._buffer) + len(data) > MAX_BUFFER_SIZE:
-                raise BufferError("Buffer size exceed limit. Call drain to clear the buffer.")
+                raise BufferError("Buffer size exceed limit. Call drain to flush the buffer.")
             self._buffer.extend(data)
         else:
             raise TypeError(f"data argument must be a bytes-like object, not {type(data).__name__}")
@@ -426,19 +653,6 @@ class _StreamWriter:
 
         This is a flow control method that blocks until data is sent. It returns
         when it is appropriate to continue writing data to the stream.
-
-        **Usage**
-
-        ```python notest
-        writer.write(data)
-        writer.drain()
-        ```
-
-        Async usage:
-        ```python notest
-        writer.write(data)  # not a blocking operation
-        await writer.drain.aio()
-        ```
         """
         data = bytes(self._buffer)
         self._buffer.clear()
@@ -467,5 +681,127 @@ class _StreamWriter:
                 raise exc
 
 
+class _StreamWriterThroughCommandRouter:
+    def __init__(
+        self,
+        object_id: str,
+        command_router_client: TaskCommandRouterClient,
+        task_id: str,
+    ) -> None:
+        self._object_id = object_id
+        self._command_router_client = command_router_client
+        self._task_id = task_id
+        self._is_closed = False
+        self._buffer = bytearray()
+        self._offset = 0
+
+    def write(self, data: Union[bytes, bytearray, memoryview, str]) -> None:
+        if self._is_closed:
+            raise ValueError("Stdin is closed. Cannot write to it.")
+        if isinstance(data, (bytes, bytearray, memoryview, str)):
+            if isinstance(data, str):
+                data = data.encode("utf-8")
+            if len(self._buffer) + len(data) > MAX_BUFFER_SIZE:
+                raise BufferError("Buffer size exceed limit. Call drain to flush the buffer.")
+            self._buffer.extend(data)
+        else:
+            raise TypeError(f"data argument must be a bytes-like object, not {type(data).__name__}")
+
+    def write_eof(self) -> None:
+        self._is_closed = True
+
+    async def drain(self) -> None:
+        eof = self._is_closed
+        # NB: There's no need to prevent writing eof twice, because the command router will ignore the second EOF.
+        if self._buffer or eof:
+            data = bytes(self._buffer)
+            await self._command_router_client.exec_stdin_write(
+                task_id=self._task_id, exec_id=self._object_id, offset=self._offset, data=data, eof=eof
+            )
+            # Only clear the buffer after writing the data to the command router is successful.
+            # This allows the client to retry drain() in the event of an exception (though
+            # exec_stdin_write already retries on transient errors, so most users will probably
+            # not do this).
+            self._buffer.clear()
+            self._offset += len(data)
+
+
+class _StreamWriter:
+    """Provides an interface to buffer and write logs to a sandbox or container process stream (`stdin`)."""
+
+    def __init__(
+        self,
+        object_id: str,
+        object_type: Literal["sandbox", "container_process"],
+        client: _Client,
+        command_router_client: Optional[TaskCommandRouterClient] = None,
+        task_id: Optional[str] = None,
+    ) -> None:
+        """mdmd:hidden"""
+        if command_router_client is None:
+            self._impl = _StreamWriterThroughServer(object_id, object_type, client)
+        else:
+            assert task_id is not None
+            assert object_type == "container_process"
+            self._impl = _StreamWriterThroughCommandRouter(object_id, command_router_client, task_id=task_id)
+
+    def write(self, data: Union[bytes, bytearray, memoryview, str]) -> None:
+        """Write data to the stream but does not send it immediately.
+
+        This is non-blocking and queues the data to an internal buffer. Must be
+        used along with the `drain()` method, which flushes the buffer.
+
+        **Usage**
+
+        ```python fixture:running_app
+        from modal import Sandbox
+
+        sandbox = Sandbox.create(
+            "bash",
+            "-c",
+            "while read line; do echo $line; done",
+            app=running_app,
+        )
+        sandbox.stdin.write(b"foo\\n")
+        sandbox.stdin.write(b"bar\\n")
+        sandbox.stdin.write_eof()
+
+        sandbox.stdin.drain()
+        sandbox.wait()
+        ```
+        """
+        self._impl.write(data)
+
+    def write_eof(self) -> None:
+        """Close the write end of the stream after the buffered data is drained.
+
+        If the process was blocked on input, it will become unblocked after
+        `write_eof()`. This method needs to be used along with the `drain()`
+        method, which flushes the EOF to the process.
+        """
+        self._impl.write_eof()
+
+    async def drain(self) -> None:
+        """Flush the write buffer and send data to the running process.
+
+        This is a flow control method that blocks until data is sent. It returns
+        when it is appropriate to continue writing data to the stream.
+
+        **Usage**
+
+        ```python notest
+        writer.write(data)
+        writer.drain()
+        ```
+
+        Async usage:
+        ```python notest
+        writer.write(data)  # not a blocking operation
+        await writer.drain.aio()
+        ```
+        """
+        await self._impl.drain()
+
+
 StreamReader = synchronize_api(_StreamReader)
 StreamWriter = synchronize_api(_StreamWriter)

modal/io_streams.pyi

@@ -1,4 +1,5 @@
 import collections.abc
+import modal._utils.task_command_router_client
 import modal.client
 import modal.stream_type
 import typing
@@ -17,6 +18,167 @@ def _container_process_logs_iterator(
 
 T = typing.TypeVar("T")
 
+class _StreamReaderThroughServer(typing.Generic[T]):
+    """A StreamReader implementation that reads from the server."""
+
+    _stream: typing.Optional[collections.abc.AsyncGenerator[typing.Optional[bytes], None]]
+
+    def __init__(
+        self,
+        file_descriptor: int,
+        object_id: str,
+        object_type: typing.Literal["sandbox", "container_process"],
+        client: modal.client._Client,
+        stream_type: modal.stream_type.StreamType = modal.stream_type.StreamType.PIPE,
+        text: bool = True,
+        by_line: bool = False,
+        deadline: typing.Optional[float] = None,
+    ) -> None:
+        """mdmd:hidden"""
+        ...
+
+    @property
+    def file_descriptor(self) -> int:
+        """Possible values are `1` for stdout and `2` for stderr."""
+        ...
+
+    async def read(self) -> T:
+        """Fetch the entire contents of the stream until EOF."""
+        ...
+
+    async def _consume_container_process_stream(self):
+        """Consume the container process stream and store messages in the buffer."""
+        ...
+
+    def _stream_container_process(self) -> collections.abc.AsyncGenerator[tuple[typing.Optional[bytes], str], None]:
+        """Streams the container process buffer to the reader."""
+        ...
+
+    def _get_logs(
+        self, skip_empty_messages: bool = True
+    ) -> collections.abc.AsyncGenerator[typing.Optional[bytes], None]:
+        """Streams sandbox or process logs from the server to the reader.
+
+        Logs returned by this method may contain partial or multiple lines at a time.
+
+        When the stream receives an EOF, it yields None. Once an EOF is received,
+        subsequent invocations will not yield logs.
+        """
+        ...
+
+    def _get_logs_by_line(self) -> collections.abc.AsyncGenerator[typing.Optional[bytes], None]:
+        """Process logs from the server and yield complete lines only."""
+        ...
+
+    def _ensure_stream(self) -> collections.abc.AsyncGenerator[typing.Optional[bytes], None]: ...
+    async def __anext__(self) -> T:
+        """mdmd:hidden"""
+        ...
+
+    async def aclose(self):
+        """mdmd:hidden"""
+        ...
+
+def _decode_bytes_stream_to_str(
+    stream: collections.abc.AsyncGenerator[bytes, None],
+) -> collections.abc.AsyncGenerator[str, None]:
+    """Incrementally decode a bytes async generator as UTF-8 without breaking on chunk boundaries.
+
+    This function uses a streaming UTF-8 decoder so that multi-byte characters split across
+    chunks are handled correctly instead of raising ``UnicodeDecodeError``.
+    """
+    ...
+
+def _stream_by_line(stream: collections.abc.AsyncGenerator[bytes, None]) -> collections.abc.AsyncGenerator[bytes, None]:
+    """Yield complete lines only (ending with
+    ), buffering partial lines until complete.
+    """
+    ...
+
+class _StreamReaderThroughCommandRouterParams:
+    """_StreamReaderThroughCommandRouterParams(file_descriptor: 'api_pb2.FileDescriptor.ValueType', task_id: str, object_id: str, command_router_client: modal._utils.task_command_router_client.TaskCommandRouterClient, deadline: Optional[float])"""
+
+    file_descriptor: int
+    task_id: str
+    object_id: str
+    command_router_client: modal._utils.task_command_router_client.TaskCommandRouterClient
+    deadline: typing.Optional[float]
+
+    def __init__(
+        self,
+        file_descriptor: int,
+        task_id: str,
+        object_id: str,
+        command_router_client: modal._utils.task_command_router_client.TaskCommandRouterClient,
+        deadline: typing.Optional[float],
+    ) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    def __repr__(self):
+        """Return repr(self)."""
+        ...
+
+    def __eq__(self, other):
+        """Return self==value."""
+        ...
+
+def _stdio_stream_from_command_router(
+    params: _StreamReaderThroughCommandRouterParams,
+) -> collections.abc.AsyncGenerator[bytes, None]:
+    """Stream raw bytes from the router client."""
+    ...
+
+class _BytesStreamReaderThroughCommandRouter(typing.Generic[T]):
+    """StreamReader implementation that will read directly from the worker that
+    hosts the sandbox.
+
+    This implementation is used for non-text streams.
+    """
+    def __init__(self, params: _StreamReaderThroughCommandRouterParams) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    @property
+    def file_descriptor(self) -> int: ...
+    async def read(self) -> T: ...
+    def __aiter__(self) -> collections.abc.AsyncIterator[T]: ...
+    async def __anext__(self) -> T: ...
+    async def aclose(self): ...
+
+class _TextStreamReaderThroughCommandRouter(typing.Generic[T]):
+    """StreamReader implementation that will read directly from the worker
+    that hosts the sandbox.
+
+    This implementation is used for text streams.
+    """
+    def __init__(self, params: _StreamReaderThroughCommandRouterParams, by_line: bool) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    @property
+    def file_descriptor(self) -> int: ...
+    async def read(self) -> T: ...
+    def __aiter__(self) -> collections.abc.AsyncIterator[T]: ...
+    async def __anext__(self) -> T: ...
+    async def aclose(self): ...
+
+class _DevnullStreamReader(typing.Generic[T]):
+    """StreamReader implementation for a stream configured with
+    StreamType.DEVNULL. Throws an error if read or any other method is
+    called.
+    """
+    def __init__(self, file_descriptor: int) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    @property
+    def file_descriptor(self) -> int: ...
+    async def read(self) -> T: ...
+    def __aiter__(self) -> collections.abc.AsyncIterator[T]: ...
+    async def __anext__(self) -> T: ...
+    async def aclose(self): ...
+
 class _StreamReader(typing.Generic[T]):
     """Retrieve logs from a stream (`stdout` or `stderr`).
 
@@ -38,9 +200,6 @@ class _StreamReader(typing.Generic[T]):
         print(f"Message: {message}")
     ```
     """
-
-    _stream: typing.Optional[collections.abc.AsyncGenerator[typing.Optional[bytes], None]]
-
     def __init__(
         self,
         file_descriptor: int,
@@ -51,6 +210,8 @@ class _StreamReader(typing.Generic[T]):
         text: bool = True,
         by_line: bool = False,
         deadline: typing.Optional[float] = None,
+        command_router_client: typing.Optional[modal._utils.task_command_router_client.TaskCommandRouterClient] = None,
+        task_id: typing.Optional[str] = None,
     ) -> None:
         """mdmd:hidden"""
         ...
@@ -76,52 +237,79 @@ class _StreamReader(typing.Generic[T]):
         """
         ...
 
-    async def _consume_container_process_stream(self):
-        """Consume the container process stream and store messages in the buffer."""
+    def __aiter__(self) -> collections.abc.AsyncIterator[T]:
+        """mdmd:hidden"""
         ...
 
-    def _stream_container_process(self) -> collections.abc.AsyncGenerator[tuple[typing.Optional[bytes], str], None]:
-        """Streams the container process buffer to the reader."""
+    async def __anext__(self) -> T:
+        """mdmd:hidden"""
         ...
 
-    def _get_logs(
-        self, skip_empty_messages: bool = True
-    ) -> collections.abc.AsyncGenerator[typing.Optional[bytes], None]:
-        """Streams sandbox or process logs from the server to the reader.
+    async def aclose(self):
+        """mdmd:hidden"""
+        ...
 
-        Logs returned by this method may contain partial or multiple lines at a time.
+class _StreamWriterThroughServer:
+    """Provides an interface to buffer and write logs to a sandbox or container process stream (`stdin`)."""
+    def __init__(
+        self, object_id: str, object_type: typing.Literal["sandbox", "container_process"], client: modal.client._Client
+    ) -> None:
+        """mdmd:hidden"""
+        ...
 
-        When the stream receives an EOF, it yields None. Once an EOF is received,
-        subsequent invocations will not yield logs.
+    def _get_next_index(self) -> int: ...
+    def write(self, data: typing.Union[bytes, bytearray, memoryview, str]) -> None:
+        """Write data to the stream but does not send it immediately.
+
+        This is non-blocking and queues the data to an internal buffer. Must be
+        used along with the `drain()` method, which flushes the buffer.
         """
         ...
 
-    def _get_logs_by_line(self) -> collections.abc.AsyncGenerator[typing.Optional[bytes], None]:
-        """Process logs from the server and yield complete lines only."""
-        ...
+    def write_eof(self) -> None:
+        """Close the write end of the stream after the buffered data is drained.
 
-    def _ensure_stream(self) -> collections.abc.AsyncGenerator[typing.Optional[bytes], None]: ...
-    def __aiter__(self) -> collections.abc.AsyncIterator[T]:
-        """mdmd:hidden"""
+        If the process was blocked on input, it will become unblocked after
+        `write_eof()`. This method needs to be used along with the `drain()`
+        method, which flushes the EOF to the process.
+        """
         ...
 
-    async def __anext__(self) -> T:
-        """mdmd:hidden"""
+    async def drain(self) -> None:
+        """Flush the write buffer and send data to the running process.
+
+        This is a flow control method that blocks until data is sent. It returns
+        when it is appropriate to continue writing data to the stream.
+        """
         ...
 
-    async def aclose(self):
-        """mdmd:hidden"""
+class _StreamWriterThroughCommandRouter:
+    def __init__(
+        self,
+        object_id: str,
+        command_router_client: modal._utils.task_command_router_client.TaskCommandRouterClient,
+        task_id: str,
+    ) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
         ...
 
+    def write(self, data: typing.Union[bytes, bytearray, memoryview, str]) -> None: ...
+    def write_eof(self) -> None: ...
+    async def drain(self) -> None: ...
+
 class _StreamWriter:
     """Provides an interface to buffer and write logs to a sandbox or container process stream (`stdin`)."""
     def __init__(
-        self, object_id: str, object_type: typing.Literal["sandbox", "container_process"], client: modal.client._Client
+        self,
+        object_id: str,
+        object_type: typing.Literal["sandbox", "container_process"],
+        client: modal.client._Client,
+        command_router_client: typing.Optional[modal._utils.task_command_router_client.TaskCommandRouterClient] = None,
+        task_id: typing.Optional[str] = None,
     ) -> None:
         """mdmd:hidden"""
         ...
 
-    def _get_next_index(self) -> int: ...
     def write(self, data: typing.Union[bytes, bytearray, memoryview, str]) -> None:
         """Write data to the stream but does not send it immediately.
 
@@ -204,9 +392,6 @@ class StreamReader(typing.Generic[T]):
         print(f"Message: {message}")
     ```
     """
-
-    _stream: typing.Optional[collections.abc.AsyncGenerator[typing.Optional[bytes], None]]
-
     def __init__(
         self,
         file_descriptor: int,
@@ -217,6 +402,8 @@ class StreamReader(typing.Generic[T]):
         text: bool = True,
         by_line: bool = False,
         deadline: typing.Optional[float] = None,
+        command_router_client: typing.Optional[modal._utils.task_command_router_client.TaskCommandRouterClient] = None,
+        task_id: typing.Optional[str] = None,
     ) -> None:
         """mdmd:hidden"""
         ...
@@ -261,70 +448,6 @@ class StreamReader(typing.Generic[T]):
 
     read: __read_spec[T, typing_extensions.Self]
 
-    class ___consume_container_process_stream_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /):
-            """Consume the container process stream and store messages in the buffer."""
-            ...
-
-        async def aio(self, /):
-            """Consume the container process stream and store messages in the buffer."""
-            ...
-
-    _consume_container_process_stream: ___consume_container_process_stream_spec[typing_extensions.Self]
-
-    class ___stream_container_process_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /) -> typing.Generator[tuple[typing.Optional[bytes], str], None, None]:
-            """Streams the container process buffer to the reader."""
-            ...
-
-        def aio(self, /) -> collections.abc.AsyncGenerator[tuple[typing.Optional[bytes], str], None]:
-            """Streams the container process buffer to the reader."""
-            ...
-
-    _stream_container_process: ___stream_container_process_spec[typing_extensions.Self]
-
-    class ___get_logs_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, skip_empty_messages: bool = True) -> typing.Generator[typing.Optional[bytes], None, None]:
-            """Streams sandbox or process logs from the server to the reader.
-
-            Logs returned by this method may contain partial or multiple lines at a time.
-
-            When the stream receives an EOF, it yields None. Once an EOF is received,
-            subsequent invocations will not yield logs.
-            """
-            ...
-
-        def aio(
-            self, /, skip_empty_messages: bool = True
-        ) -> collections.abc.AsyncGenerator[typing.Optional[bytes], None]:
-            """Streams sandbox or process logs from the server to the reader.
-
-            Logs returned by this method may contain partial or multiple lines at a time.
-
-            When the stream receives an EOF, it yields None. Once an EOF is received,
-            subsequent invocations will not yield logs.
-            """
-            ...
-
-    _get_logs: ___get_logs_spec[typing_extensions.Self]
-
-    class ___get_logs_by_line_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /) -> typing.Generator[typing.Optional[bytes], None, None]:
-            """Process logs from the server and yield complete lines only."""
-            ...
-
-        def aio(self, /) -> collections.abc.AsyncGenerator[typing.Optional[bytes], None]:
-            """Process logs from the server and yield complete lines only."""
-            ...
-
-    _get_logs_by_line: ___get_logs_by_line_spec[typing_extensions.Self]
-
-    class ___ensure_stream_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /) -> typing.Generator[typing.Optional[bytes], None, None]: ...
-        def aio(self, /) -> collections.abc.AsyncGenerator[typing.Optional[bytes], None]: ...
-
-    _ensure_stream: ___ensure_stream_spec[typing_extensions.Self]
-
     def __iter__(self) -> typing.Iterator[T]:
         """mdmd:hidden"""
         ...
@@ -352,12 +475,16 @@ class StreamReader(typing.Generic[T]):
 class StreamWriter:
     """Provides an interface to buffer and write logs to a sandbox or container process stream (`stdin`)."""
     def __init__(
-        self, object_id: str, object_type: typing.Literal["sandbox", "container_process"], client: modal.client.Client
+        self,
+        object_id: str,
+        object_type: typing.Literal["sandbox", "container_process"],
+        client: modal.client.Client,
+        command_router_client: typing.Optional[modal._utils.task_command_router_client.TaskCommandRouterClient] = None,
+        task_id: typing.Optional[str] = None,
     ) -> None:
         """mdmd:hidden"""
         ...
 
-    def _get_next_index(self) -> int: ...
     def write(self, data: typing.Union[bytes, bytearray, memoryview, str]) -> None:
         """Write data to the stream but does not send it immediately.
 

{modal-1.2.1.dev11.dist-info → modal-1.2.1.dev13.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.2.1.dev11
+Version: 1.2.1.dev13
 Summary: Python client library for Modal
 Author-email: Modal Labs <support@modal.com>
 License: Apache-2.0

{modal-1.2.1.dev11.dist-info → modal-1.2.1.dev13.dist-info}/RECORD

@@ -24,13 +24,13 @@ modal/app.pyi,sha256=AUV5Rp8qQrZJTP2waoKHFY7rYgsXNMYibMcCAQKuSeo,50544
 modal/billing.py,sha256=zmQ3bcCJlwa4KD1IA_QgdWpm1pn13c-7qfy79iEauYI,195
 modal/call_graph.py,sha256=1g2DGcMIJvRy-xKicuf63IVE98gJSnQsr8R_NVMptNc,2581
 modal/client.py,sha256=kyAIVB3Ay-XKJizQ_1ufUFB__EagV0MLmHJpyYyJ7J0,18636
-modal/client.pyi,sha256=ph8_OsWEq_LudTDG7jrAv84RKbPE2JfPw8SiCFAXLf8,15831
+modal/client.pyi,sha256=ly6S74QtNMbeJ0kqCRdVsoppgC7cgA_gFuw9Zd6H0UI,15831
 modal/cloud_bucket_mount.py,sha256=I2GRXYhOWLIz2kJZjXu75jAm9EJkBNcutGc6jR2ReUw,5928
 modal/cloud_bucket_mount.pyi,sha256=VuUOipMIHqFXMkD-3g2bsoqpSxV5qswlFHDOqPQzYAo,7405
 modal/cls.py,sha256=ZxzivE3fNci4-A5uyBYNAzXMXtdqDg3gnYvgbdy5fhg,40384
 modal/cls.pyi,sha256=jJsDPFoqzM4ht-V-e-xEJKJ5TINLF0fYtoBm_UeAW5Y,27281
 modal/config.py,sha256=hpgkgQKbjzo6gVbRzXQrky72_KpdSEm65RNi1M2iNjc,13038
-modal/container_process.py,sha256=Mutkl7sg_WR5zP4oJiWSC-3UdYRqp0zdKi1shZbi-bk,6996
+modal/container_process.py,sha256=DnqlgHiM-7rgVdJNcaXyZlXFD6DFLxEgMSFkieQ6Oj0,7452
 modal/container_process.pyi,sha256=9m-st3hCUlNN1GOTctfPPvIvoLtEl7FbuGWwif5-7YU,6037
 modal/dict.py,sha256=XkaxuojMVtcc4bZvCjJcd6DedU5xxfF8H4w-mDzFPCo,21580
 modal/dict.pyi,sha256=deOiwuwZtwXqedC3h19SwoQIWc4mUnDTBM5XkONt48Y,31712
@@ -45,8 +45,8 @@ modal/functions.pyi,sha256=Z6VuukLrjASAgf0kV9I6c09WvP_b2gCujX6f9j2bBaw,37988
 modal/gpu.py,sha256=Fe5ORvVPDIstSq1xjmM6OoNgLYFWvogP9r5BgmD3hYg,6769
 modal/image.py,sha256=HDkOnhIAN8g63a8LTN4J5SjC9ciReFQQJIxTS2z5KFM,107216
 modal/image.pyi,sha256=dMvMwAuvWkNN2BRYJFijkEy2m_xtEXgCKK0T7FVldsc,77514
-modal/io_streams.py,sha256=hZOVc5beOAm8S_VQQmmKUbk_BJ9OltN83RY0yMPqUDo,16545
-modal/io_streams.pyi,sha256=aOun_jUFKHSJyUY6-7gKvNoxzcULsa8_hxdtEO7v-gk,13980
+modal/io_streams.py,sha256=Kv-No6WcNBouwdoogwHafOsmPOKqxTpvVGLU0mM6xMc,29564
+modal/io_streams.pyi,sha256=h7qtAbj8LsN-eJKAGjBhnMBegvWprc_0AmwVFi6rj2Y,18084
 modal/mount.py,sha256=G7_xhQMZqokgfsaFLMch0YR3fs-OUNqYUm3f4jHTSMQ,33161
 modal/mount.pyi,sha256=MD_zV2M7eCWxbOpQRjU60aHevN-bmbiywaCX82QoFlw,15380
 modal/network_file_system.py,sha256=ZdEIRgdcR-p_ILyw_AecEtPOhhrSWJeADYCtFnhtaHM,13509
@@ -156,7 +156,7 @@ modal/experimental/__init__.py,sha256=9gkVuDmu3m4TlKoU3MzEtTOemUSs8EEOWba40s7Aa0
 modal/experimental/flash.py,sha256=C4sef08rARYFllsgtqukFmYL18SZW0_JpMS0BejDcUs,28552
 modal/experimental/flash.pyi,sha256=vV_OQhtdrPn8SW0XrBK-aLLHHIvxAzLzwFbWrke-m74,15463
 modal/experimental/ipython.py,sha256=TrCfmol9LGsRZMeDoeMPx3Hv3BFqQhYnmD_iH0pqdhk,2904
-modal-1.2.1.dev11.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
+modal-1.2.1.dev13.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
 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=d_CQUGQ0rfw28u75I2mov9AlS773z9rG40-yq5o7g2U,6359
@@ -184,10 +184,10 @@ modal_proto/task_command_router_pb2.py,sha256=_pD2ZpU0bNzhwBdzmLoLyLtAtftI_Agxwn
 modal_proto/task_command_router_pb2.pyi,sha256=EyDgXPLr7alqjXYERV8w_MPuO404x0uCppmSkrfE9IE,14589
 modal_proto/task_command_router_pb2_grpc.py,sha256=uEQ0HdrCp8v-9bB5yIic9muA8spCShLHY6Bz9cCgOUE,10114
 modal_proto/task_command_router_pb2_grpc.pyi,sha256=s3Yxsrawdj4nr8vqQqsAxyX6ilWaGbdECy425KKbLIA,3301
-modal_version/__init__.py,sha256=16uG298P5zLwLoTMMHjlqZF78qdA8tqhO7F9_yVUFvg,121
+modal_version/__init__.py,sha256=BvNzpPJEyoSPk632gFDNj08JAPD46g42lR-teo7dEP8,121
 modal_version/__main__.py,sha256=2FO0yYQQwDTh6udt1h-cBnGd1c4ZyHnHSI4BksxzVac,105
-modal-1.2.1.dev11.dist-info/METADATA,sha256=VBI4dhCiWGWn6pJE5UqZur7MkPBsNM_0jghxFSzbz0M,2484
-modal-1.2.1.dev11.dist-info/WHEEL,sha256=1tXe9gY0PYatrMPMDd6jXqjfpz_B-Wqm32CPfRC58XU,91
-modal-1.2.1.dev11.dist-info/entry_points.txt,sha256=An-wYgeEUnm6xzrAP9_NTSTSciYvvEWsMZILtYrvpAI,46
-modal-1.2.1.dev11.dist-info/top_level.txt,sha256=4BWzoKYREKUZ5iyPzZpjqx4G8uB5TWxXPDwibLcVa7k,43
-modal-1.2.1.dev11.dist-info/RECORD,,
+modal-1.2.1.dev13.dist-info/METADATA,sha256=4JrQuKWcdeqkB350h27KFdy5O4gp4c4rk8EBdsBKSz0,2484
+modal-1.2.1.dev13.dist-info/WHEEL,sha256=1tXe9gY0PYatrMPMDd6jXqjfpz_B-Wqm32CPfRC58XU,91
+modal-1.2.1.dev13.dist-info/entry_points.txt,sha256=An-wYgeEUnm6xzrAP9_NTSTSciYvvEWsMZILtYrvpAI,46
+modal-1.2.1.dev13.dist-info/top_level.txt,sha256=4BWzoKYREKUZ5iyPzZpjqx4G8uB5TWxXPDwibLcVa7k,43
+modal-1.2.1.dev13.dist-info/RECORD,,

modal_version/__init__.py

@@ -1,4 +1,4 @@
 # Copyright Modal Labs 2025
 """Supplies the current version of the modal client library."""
 
-__version__ = "1.2.1.dev11"
+__version__ = "1.2.1.dev13"