modal 1.0.4.dev10__py3-none-any.whl → 1.0.5__py3-none-any.whl

modal/environments.pyi

@@ -7,20 +7,42 @@ import typing
 import typing_extensions
 
 class EnvironmentSettings:
+    """EnvironmentSettings(image_builder_version: str, webhook_suffix: str)"""
+
     image_builder_version: str
     webhook_suffix: str
 
-    def __init__(self, image_builder_version: str, webhook_suffix: str) -> None: ...
-    def __repr__(self): ...
-    def __eq__(self, other): ...
-    def __setattr__(self, name, value): ...
-    def __delattr__(self, name): ...
-    def __hash__(self): ...
+    def __init__(self, image_builder_version: str, webhook_suffix: str) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    def __repr__(self):
+        """Return repr(self)."""
+        ...
+
+    def __eq__(self, other):
+        """Return self==value."""
+        ...
+
+    def __setattr__(self, name, value):
+        """Implement setattr(self, name, value)."""
+        ...
+
+    def __delattr__(self, name):
+        """Implement delattr(self, name)."""
+        ...
+
+    def __hash__(self):
+        """Return hash(self)."""
+        ...
 
 class _Environment(modal._object._Object):
     _settings: EnvironmentSettings
 
-    def __init__(self): ...
+    def __init__(self):
+        """mdmd:hidden"""
+        ...
+
     def _hydrate_metadata(self, metadata: google.protobuf.message.Message): ...
     @staticmethod
     def from_name(name: str, *, create_if_missing: bool = False): ...
@@ -32,7 +54,10 @@ class _Environment(modal._object._Object):
 class Environment(modal.object.Object):
     _settings: EnvironmentSettings
 
-    def __init__(self): ...
+    def __init__(self):
+        """mdmd:hidden"""
+        ...
+
     def _hydrate_metadata(self, metadata: google.protobuf.message.Message): ...
     @staticmethod
     def from_name(name: str, *, create_if_missing: bool = False): ...
@@ -93,6 +118,13 @@ class __list_environments_spec(typing_extensions.Protocol):
 
 list_environments: __list_environments_spec
 
-def ensure_env(environment_name: typing.Optional[str] = None) -> str: ...
+def ensure_env(environment_name: typing.Optional[str] = None) -> str:
+    """Override config environment with environment from environment_name
+
+    This is necessary since a cli command that runs Modal code, without explicit
+    environment specification wouldn't pick up the environment specified in a
+    command line flag otherwise, e.g. when doing `modal run --env=foo`
+    """
+    ...
 
 ENVIRONMENT_CACHE: dict[str, _Environment]

modal/exception.py

@@ -2,11 +2,15 @@
 import random
 import signal
 
+import synchronicity.exceptions
+
+UserCodeException = synchronicity.exceptions.UserCodeException  # Deprecated type used for return_exception wrapping
+
 
 class Error(Exception):
     """
-    Base class for all Modal errors. See [`modal.exception`](/docs/reference/modal.exception) for the specialized
-    error classes.
+    Base class for all Modal errors. See [`modal.exception`](https://modal.com/docs/reference/modal.exception)
+    for the specialized error classes.
 
     **Usage**
 

modal/experimental/__init__.py

@@ -1,5 +1,7 @@
 # Copyright Modal Labs 2025
+import asyncio
 import os
+import sys
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Literal, Optional, Union
@@ -11,11 +13,13 @@ from .._functions import _Function
 from .._object import _get_environment_name
 from .._partial_function import _clustered
 from .._runtime.container_io_manager import _ContainerIOManager
+from .._tunnel import _forward as _forward_tunnel
 from .._utils.async_utils import synchronize_api, synchronizer
 from .._utils.deprecation import deprecation_warning
 from .._utils.grpc_utils import retry_transient_errors
 from ..client import _Client
 from ..cls import _Obj
+from ..config import logger
 from ..exception import InvalidError
 from ..image import DockerfileSpec, ImageBuilderVersion, _Image, _ImageRegistryConfig
 from ..secret import _Secret
@@ -209,3 +213,89 @@ async def update_autoscaler(
 
     request = api_pb2.FunctionUpdateSchedulingParamsRequest(function_id=f.object_id, settings=settings)
     await retry_transient_errors(client.stub.FunctionUpdateSchedulingParams, request)
+
+
+class _FlashManager:
+    def __init__(self, client: _Client, port: int):
+        self.client = client
+        self.port = port
+        self.tunnel_manager = _forward_tunnel(port, client=client)
+        self.stopped = False
+
+    async def _start(self):
+        self.tunnel = await self.tunnel_manager.__aenter__()
+
+        hostname = self.tunnel.url.split("://")[1]
+        if ":" in hostname:
+            host, port = hostname.split(":")
+        else:
+            host = hostname
+            port = "443"
+
+        self.heartbeat_task = asyncio.create_task(self._run_heartbeat(host, int(port)))
+
+    async def _run_heartbeat(self, host: str, port: int):
+        first_registration = True
+        while True:
+            try:
+                resp = await self.client.stub.FlashContainerRegister(
+                    api_pb2.FlashContainerRegisterRequest(
+                        priority=10,
+                        weight=5,
+                        host=host,
+                        port=port,
+                    ),
+                    timeout=10,
+                )
+                if first_registration:
+                    logger.warning(f"[Modal Flash] Listening at {resp.url}")
+                    first_registration = False
+            except asyncio.CancelledError:
+                logger.warning("[Modal Flash] Shutting down...")
+                break
+            except Exception as e:
+                logger.error(f"[Modal Flash] Heartbeat failed: {e}")
+
+            try:
+                await asyncio.sleep(1)
+            except asyncio.CancelledError:
+                logger.warning("[Modal Flash] Shutting down...")
+                break
+
+    async def stop(self):
+        self.heartbeat_task.cancel()
+        await retry_transient_errors(
+            self.client.stub.FlashContainerDeregister,
+            api_pb2.FlashContainerDeregisterRequest(),
+        )
+
+        self.stopped = True
+        logger.warning(f"[Modal Flash] No longer accepting new requests on {self.tunnel.url}.")
+
+        # NOTE(gongy): We skip calling TunnelStop to avoid interrupting in-flight requests.
+        # It is up to the user to wait after calling .stop() to drain in-flight requests.
+
+    async def close(self):
+        if not self.stopped:
+            await self.stop()
+
+        logger.warning(f"[Modal Flash] Closing tunnel on {self.tunnel.url}.")
+        await self.tunnel_manager.__aexit__(*sys.exc_info())
+
+
+FlashManager = synchronize_api(_FlashManager)
+
+
+@synchronizer.create_blocking
+async def flash_forward(port: int) -> _FlashManager:
+    """
+    Forward a port to the Modal Flash service, exposing that port as a stable web endpoint.
+
+    This is a highly experimental method that can break or be removed at any time without warning.
+    Do not use this method unless explicitly instructed to do so by Modal support.
+    """
+    client = await _Client.from_env()
+
+    manager = _FlashManager(client, port)
+    await manager._start()
+    return manager

modal/experimental/ipython.py

@@ -21,7 +21,7 @@ class ModalMagics(Magics):
         **Example:**
 
         ```python notest
-        %modal from main/my-app import my_function, MyClass as Foo
+        %modal from my-app import my_function, MyClass as Foo
 
         # Now you can call my_function() and Foo from your notebook.
         my_function.remote()
@@ -30,7 +30,7 @@ class ModalMagics(Magics):
         """
         line = line.strip()
         if not line.startswith("from "):
-            print("Invalid syntax. Use: %modal from <env>/<app> import <function|Class>[, <function|Class> [as alias]]")
+            print("Invalid syntax. Use: %modal from [env/]<app> import <function|Class>[, <function|Class> [as alias]]")
             return
 
         # Remove the initial "from "
@@ -40,11 +40,12 @@ class ModalMagics(Magics):
             print("Invalid syntax. Missing 'import' keyword.")
             return
 
-        # Parse environment and app from "env/app"
+        # Parse environment and app from "[env/]app"
+        environment: str | None
         if "/" not in env_app_part:
-            print("Invalid app specification. Expected format: <env>/<app>")
-            return
-        environment, app = env_app_part.split("/", 1)
+            environment, app = None, env_app_part
+        else:
+            environment, app = env_app_part.split("/", 1)
 
         # Parse the import items (multiple imports separated by commas)
         import_items = [item.strip() for item in import_part.split(",")]
@@ -73,7 +74,10 @@ class ModalMagics(Magics):
 
             # Set the loaded object in the notebook namespace
             self.shell.user_ns[alias] = obj  # type: ignore
-            print(f"Loaded {alias!r} from environment {environment!r} and app {app!r}.")
+            if environment:
+                print(f"Loaded {alias!r} from environment {environment!r} and app {app!r}.")
+            else:
+                print(f"Loaded {alias!r} from app {app!r}.")
 
 
 def load_ipython_extension(ipython):

modal/file_io.pyi

@@ -6,12 +6,24 @@ 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 _delete_bytes(file: _FileIO, start: typing.Optional[int] = None, end: typing.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.
+    """
+    ...
+
 async def _replace_bytes(
     file: _FileIO, data: bytes, start: typing.Optional[int] = None, end: typing.Optional[int] = None
-) -> 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.
+    """
+    ...
 
 class FileWatchEventType(enum.Enum):
     Unknown = "Unknown"
@@ -21,20 +33,51 @@ class FileWatchEventType(enum.Enum):
     Remove = "Remove"
 
 class FileWatchEvent:
+    """FileWatchEvent(paths: list[str], type: modal.file_io.FileWatchEventType)"""
+
     paths: list[str]
     type: FileWatchEventType
 
-    def __init__(self, paths: list[str], type: FileWatchEventType) -> None: ...
-    def __repr__(self): ...
-    def __eq__(self, other): ...
+    def __init__(self, paths: list[str], type: FileWatchEventType) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    def __repr__(self):
+        """Return repr(self)."""
+        ...
+
+    def __eq__(self, other):
+        """Return self==value."""
+        ...
 
 class _FileIO(typing.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()
+    ```
+    """
+
     _task_id: str
     _file_descriptor: str
     _client: modal.client._Client
     _watch_output_buffer: list[typing.Union[bytes, None, Exception]]
 
-    def __init__(self, client: modal.client._Client, task_id: str) -> None: ...
+    def __init__(self, client: modal.client._Client, task_id: str) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
     def _validate_mode(self, mode: str) -> None: ...
     def _consume_output(self, exec_id: str) -> typing.AsyncIterator[typing.Union[bytes, None, Exception]]: ...
     async def _consume_watch_output(self, exec_id: str) -> None: ...
@@ -49,21 +92,60 @@ class _FileIO(typing.Generic[T]):
         mode: typing.Union[_typeshed.OpenTextMode, _typeshed.OpenBinaryMode],
         client: modal.client._Client,
         task_id: str,
-    ) -> _FileIO: ...
+    ) -> _FileIO:
+        """Create a new FileIO handle."""
+        ...
+
     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: ...
+    async def read(self, n: typing.Optional[int] = None) -> T:
+        """Read n bytes from the current position, or the entire remaining file if n is None."""
+        ...
+
+    async def readline(self) -> T:
+        """Read a single line from the current position."""
+        ...
+
+    async def readlines(self) -> typing.Sequence[T]:
+        """Read all lines from the current position."""
+        ...
+
+    async def write(self, data: typing.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.
+        """
+        ...
+
+    async def flush(self) -> None:
+        """Flush the buffer to disk."""
+        ...
+
     def _get_whence(self, whence: int): ...
-    async def seek(self, offset: int, whence: int = 0) -> None: ...
+    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).
+        """
+        ...
+
     @classmethod
-    async def ls(cls, path: str, client: modal.client._Client, task_id: str) -> list[str]: ...
+    async def ls(cls, path: str, client: modal.client._Client, task_id: str) -> list[str]:
+        """List the contents of the provided directory."""
+        ...
+
     @classmethod
-    async def mkdir(cls, path: str, client: modal.client._Client, task_id: str, parents: bool = False) -> None: ...
+    async def mkdir(cls, path: str, client: modal.client._Client, task_id: str, parents: bool = False) -> None:
+        """Create a new directory."""
+        ...
+
     @classmethod
-    async def rm(cls, path: str, client: modal.client._Client, task_id: str, recursive: bool = False) -> None: ...
+    async def rm(cls, path: str, client: modal.client._Client, task_id: str, recursive: bool = False) -> None:
+        """Remove a file or directory in the Sandbox."""
+        ...
+
     @classmethod
     def watch(
         cls,
@@ -75,7 +157,10 @@ class _FileIO(typing.Generic[T]):
         timeout: typing.Optional[int] = None,
     ) -> typing.AsyncIterator[FileWatchEvent]: ...
     async def _close(self) -> None: ...
-    async def close(self) -> None: ...
+    async def close(self) -> None:
+        """Flush the buffer and close the file."""
+        ...
+
     def _check_writable(self) -> None: ...
     def _check_readable(self) -> None: ...
     def _check_closed(self) -> None: ...
@@ -83,22 +168,46 @@ class _FileIO(typing.Generic[T]):
     async def __aexit__(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: ...
+    def __call__(self, /, file: FileIO, start: typing.Optional[int] = None, end: typing.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.
+        """
+        ...
+
+    async def aio(self, /, file: FileIO, start: typing.Optional[int] = None, end: typing.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.
+        """
+        ...
 
 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: ...
+    ) -> 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.
+        """
+        ...
+
     async def aio(
         self, /, file: FileIO, data: bytes, start: typing.Optional[int] = None, end: typing.Optional[int] = None
-    ) -> 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.
+        """
+        ...
 
 replace_bytes: __replace_bytes_spec
 
@@ -107,6 +216,24 @@ SUPERSELF = typing.TypeVar("SUPERSELF", covariant=True)
 T_INNER = typing.TypeVar("T_INNER", covariant=True)
 
 class FileIO(typing.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()
+    ```
+    """
+
     _task_id: str
     _file_descriptor: str
     _client: modal.client.Client
@@ -154,7 +281,9 @@ class FileIO(typing.Generic[T]):
         mode: typing.Union[_typeshed.OpenTextMode, _typeshed.OpenBinaryMode],
         client: modal.client.Client,
         task_id: str,
-    ) -> FileIO: ...
+    ) -> FileIO:
+        """Create a new FileIO handle."""
+        ...
 
     class ___make_read_request_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /, n: typing.Optional[int]) -> bytes: ...
@@ -163,49 +292,106 @@ class FileIO(typing.Generic[T]):
     _make_read_request: ___make_read_request_spec[typing_extensions.Self]
 
     class __read_spec(typing_extensions.Protocol[T_INNER, SUPERSELF]):
-        def __call__(self, /, n: typing.Optional[int] = None) -> T_INNER: ...
-        async def aio(self, /, n: typing.Optional[int] = None) -> T_INNER: ...
+        def __call__(self, /, n: typing.Optional[int] = None) -> T_INNER:
+            """Read n bytes from the current position, or the entire remaining file if n is None."""
+            ...
+
+        async def aio(self, /, n: typing.Optional[int] = None) -> T_INNER:
+            """Read n bytes from the current position, or the entire remaining file if n is None."""
+            ...
 
     read: __read_spec[T, typing_extensions.Self]
 
     class __readline_spec(typing_extensions.Protocol[T_INNER, SUPERSELF]):
-        def __call__(self, /) -> T_INNER: ...
-        async def aio(self, /) -> T_INNER: ...
+        def __call__(self, /) -> T_INNER:
+            """Read a single line from the current position."""
+            ...
+
+        async def aio(self, /) -> T_INNER:
+            """Read a single line from the current position."""
+            ...
 
     readline: __readline_spec[T, typing_extensions.Self]
 
     class __readlines_spec(typing_extensions.Protocol[T_INNER, SUPERSELF]):
-        def __call__(self, /) -> typing.Sequence[T_INNER]: ...
-        async def aio(self, /) -> typing.Sequence[T_INNER]: ...
+        def __call__(self, /) -> typing.Sequence[T_INNER]:
+            """Read all lines from the current position."""
+            ...
+
+        async def aio(self, /) -> typing.Sequence[T_INNER]:
+            """Read all lines from the current position."""
+            ...
 
     readlines: __readlines_spec[T, typing_extensions.Self]
 
     class __write_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, data: typing.Union[bytes, str]) -> None: ...
-        async def aio(self, /, data: typing.Union[bytes, str]) -> None: ...
+        def __call__(self, /, data: typing.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.
+            """
+            ...
+
+        async def aio(self, /, data: typing.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.
+            """
+            ...
 
     write: __write_spec[typing_extensions.Self]
 
     class __flush_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /) -> None: ...
-        async def aio(self, /) -> None: ...
+        def __call__(self, /) -> None:
+            """Flush the buffer to disk."""
+            ...
+
+        async def aio(self, /) -> None:
+            """Flush the buffer to disk."""
+            ...
 
     flush: __flush_spec[typing_extensions.Self]
 
     def _get_whence(self, whence: int): ...
 
     class __seek_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, offset: int, whence: int = 0) -> None: ...
-        async def aio(self, /, offset: int, whence: int = 0) -> None: ...
+        def __call__(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).
+            """
+            ...
+
+        async def aio(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).
+            """
+            ...
 
     seek: __seek_spec[typing_extensions.Self]
 
     @classmethod
-    def ls(cls, path: str, client: modal.client.Client, task_id: str) -> list[str]: ...
+    def ls(cls, path: str, client: modal.client.Client, task_id: str) -> list[str]:
+        """List the contents of the provided directory."""
+        ...
+
     @classmethod
-    def mkdir(cls, path: str, client: modal.client.Client, task_id: str, parents: bool = False) -> None: ...
+    def mkdir(cls, path: str, client: modal.client.Client, task_id: str, parents: bool = False) -> None:
+        """Create a new directory."""
+        ...
+
     @classmethod
-    def rm(cls, path: str, client: modal.client.Client, task_id: str, recursive: bool = False) -> None: ...
+    def rm(cls, path: str, client: modal.client.Client, task_id: str, recursive: bool = False) -> None:
+        """Remove a file or directory in the Sandbox."""
+        ...
+
     @classmethod
     def watch(
         cls,
@@ -224,8 +410,13 @@ class FileIO(typing.Generic[T]):
     _close: ___close_spec[typing_extensions.Self]
 
     class __close_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /) -> None: ...
-        async def aio(self, /) -> None: ...
+        def __call__(self, /) -> None:
+            """Flush the buffer and close the file."""
+            ...
+
+        async def aio(self, /) -> None:
+            """Flush the buffer and close the file."""
+            ...
 
     close: __close_spec[typing_extensions.Self]