modal 1.0.5.dev2__py3-none-any.whl → 1.0.5.dev4__py3-none-any.whl

modal/sandbox.pyi

@@ -28,6 +28,12 @@ import typing_extensions
 def _validate_exec_args(entrypoint_args: collections.abc.Sequence[str]) -> None: ...
 
 class _Sandbox(modal._object._Object):
+    """A `Sandbox` object lets you interact with a running sandbox. This API is similar to Python's
+    [asyncio.subprocess.Process](https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.subprocess.Process).
+
+    Refer to the [guide](https://modal.com/docs/guide/sandbox) on how to spawn and use sandboxes.
+    """
+
     _result: typing.Optional[modal_proto.api_pb2.GenericResult]
     _stdout: modal.io_streams._StreamReader[str]
     _stderr: modal.io_streams._StreamReader[str]
@@ -64,7 +70,10 @@ class _Sandbox(modal._object._Object):
         _experimental_scheduler_placement: typing.Optional[modal.scheduler_placement.SchedulerPlacement] = None,
         enable_snapshot: bool = False,
         verbose: bool = False,
-    ) -> _Sandbox: ...
+    ) -> _Sandbox:
+        """mdmd:hidden"""
+        ...
+
     @staticmethod
     async def create(
         *entrypoint_args: str,
@@ -95,7 +104,21 @@ class _Sandbox(modal._object._Object):
         _experimental_enable_snapshot: bool = False,
         _experimental_scheduler_placement: typing.Optional[modal.scheduler_placement.SchedulerPlacement] = None,
         client: typing.Optional[modal.client._Client] = None,
-    ) -> _Sandbox: ...
+    ) -> _Sandbox:
+        """Create a new Sandbox to run untrusted, arbitrary code. The Sandbox's corresponding container
+        will be created asynchronously.
+
+        **Usage**
+
+        ```python
+        app = modal.App.lookup('sandbox-hello-world', create_if_missing=True)
+        sandbox = modal.Sandbox.create("echo", "hello world", app=app)
+        print(sandbox.stdout.read())
+        sandbox.wait()
+        ```
+        """
+        ...
+
     @staticmethod
     async def _create(
         *entrypoint_args: str,
@@ -130,13 +153,55 @@ class _Sandbox(modal._object._Object):
     ): ...
     def _hydrate_metadata(self, handle_metadata: typing.Optional[google.protobuf.message.Message]): ...
     @staticmethod
-    async def from_id(sandbox_id: str, client: typing.Optional[modal.client._Client] = None) -> _Sandbox: ...
-    async def set_tags(self, tags: dict[str, str], *, client: typing.Optional[modal.client._Client] = None): ...
-    async def snapshot_filesystem(self, timeout: int = 55) -> modal.image._Image: ...
-    async def wait(self, raise_on_termination: bool = True): ...
-    async def tunnels(self, timeout: int = 50) -> dict[int, modal._tunnel.Tunnel]: ...
-    async def terminate(self) -> None: ...
-    async def poll(self) -> typing.Optional[int]: ...
+    async def from_id(sandbox_id: str, client: typing.Optional[modal.client._Client] = None) -> _Sandbox:
+        """Construct a Sandbox from an id and look up the Sandbox result.
+
+        The ID of a Sandbox object can be accessed using `.object_id`.
+        """
+        ...
+
+    async def set_tags(self, tags: dict[str, str], *, client: typing.Optional[modal.client._Client] = None):
+        """Set tags (key-value pairs) on the Sandbox. Tags can be used to filter results in `Sandbox.list`."""
+        ...
+
+    async def snapshot_filesystem(self, timeout: int = 55) -> modal.image._Image:
+        """Snapshot the filesystem of the Sandbox.
+
+        Returns an [`Image`](https://modal.com/docs/reference/modal.Image) object which
+        can be used to spawn a new Sandbox with the same filesystem.
+        """
+        ...
+
+    async def wait(self, raise_on_termination: bool = True):
+        """Wait for the Sandbox to finish running."""
+        ...
+
+    async def tunnels(self, timeout: int = 50) -> dict[int, modal._tunnel.Tunnel]:
+        """Get Tunnel metadata for the sandbox.
+
+        Raises `SandboxTimeoutError` if the tunnels are not available after the timeout.
+
+        Returns a dictionary of `Tunnel` objects which are keyed by the container port.
+
+        NOTE: Previous to client [v0.64.153](https://modal.com/docs/reference/changelog#064153-2024-09-30), this
+        returned a list of `TunnelData` objects.
+        """
+        ...
+
+    async def terminate(self) -> None:
+        """Terminate Sandbox execution.
+
+        This is a no-op if the Sandbox has already finished running.
+        """
+        ...
+
+    async def poll(self) -> typing.Optional[int]:
+        """Check if the Sandbox has finished running.
+
+        Returns `None` if the Sandbox is still running, else returns the exit code.
+        """
+        ...
+
     async def _get_task_id(self) -> str: ...
     @typing.overload
     async def exec(
@@ -175,35 +240,75 @@ class _Sandbox(modal._object._Object):
     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]: ...
-    async def ls(self, path: str) -> list[str]: ...
-    async def mkdir(self, path: str, parents: bool = False) -> None: ...
-    async def rm(self, path: str, recursive: bool = False) -> None: ...
+    async def ls(self, path: str) -> list[str]:
+        """List the contents of a directory in the Sandbox."""
+        ...
+
+    async def mkdir(self, path: str, parents: bool = False) -> None:
+        """Create a new directory in the Sandbox."""
+        ...
+
+    async def rm(self, path: str, recursive: bool = False) -> None:
+        """Remove a file or directory in the Sandbox."""
+        ...
+
     def watch(
         self,
         path: str,
         filter: typing.Optional[list[modal.file_io.FileWatchEventType]] = None,
         recursive: typing.Optional[bool] = None,
         timeout: typing.Optional[int] = None,
-    ) -> typing.AsyncIterator[modal.file_io.FileWatchEvent]: ...
+    ) -> typing.AsyncIterator[modal.file_io.FileWatchEvent]:
+        """Watch a file or directory in the Sandbox for changes."""
+        ...
+
     @property
-    def stdout(self) -> modal.io_streams._StreamReader[str]: ...
+    def stdout(self) -> modal.io_streams._StreamReader[str]:
+        """[`StreamReader`](https://modal.com/docs/reference/modal.io_streams#modalio_streamsstreamreader) for
+        the sandbox's stdout stream.
+        """
+        ...
+
     @property
-    def stderr(self) -> modal.io_streams._StreamReader[str]: ...
+    def stderr(self) -> modal.io_streams._StreamReader[str]:
+        """[`StreamReader`](https://modal.com/docs/reference/modal.io_streams#modalio_streamsstreamreader) for
+        the Sandbox's stderr stream.
+        """
+        ...
+
     @property
-    def stdin(self) -> modal.io_streams._StreamWriter: ...
+    def stdin(self) -> modal.io_streams._StreamWriter:
+        """[`StreamWriter`](https://modal.com/docs/reference/modal.io_streams#modalio_streamsstreamwriter) for
+        the Sandbox's stdin stream.
+        """
+        ...
+
     @property
-    def returncode(self) -> typing.Optional[int]: ...
+    def returncode(self) -> typing.Optional[int]:
+        """Return code of the Sandbox process if it has finished running, else `None`."""
+        ...
+
     @staticmethod
     def list(
         *,
         app_id: typing.Optional[str] = None,
         tags: typing.Optional[dict[str, str]] = None,
         client: typing.Optional[modal.client._Client] = None,
-    ) -> collections.abc.AsyncGenerator[_Sandbox, None]: ...
+    ) -> collections.abc.AsyncGenerator[_Sandbox, None]:
+        """List all Sandboxes for the current Environment or App ID (if specified). If tags are specified, only
+        Sandboxes that have at least those tags are returned. Returns an iterator over `Sandbox` objects.
+        """
+        ...
 
 SUPERSELF = typing.TypeVar("SUPERSELF", covariant=True)
 
 class Sandbox(modal.object.Object):
+    """A `Sandbox` object lets you interact with a running sandbox. This API is similar to Python's
+    [asyncio.subprocess.Process](https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.subprocess.Process).
+
+    Refer to the [guide](https://modal.com/docs/guide/sandbox) on how to spawn and use sandboxes.
+    """
+
     _result: typing.Optional[modal_proto.api_pb2.GenericResult]
     _stdout: modal.io_streams.StreamReader[str]
     _stderr: modal.io_streams.StreamReader[str]
@@ -212,7 +317,10 @@ class Sandbox(modal.object.Object):
     _tunnels: typing.Optional[dict[int, modal._tunnel.Tunnel]]
     _enable_snapshot: bool
 
-    def __init__(self, *args, **kwargs): ...
+    def __init__(self, *args, **kwargs):
+        """mdmd:hidden"""
+        ...
+
     @staticmethod
     def _new(
         entrypoint_args: collections.abc.Sequence[str],
@@ -240,7 +348,9 @@ class Sandbox(modal.object.Object):
         _experimental_scheduler_placement: typing.Optional[modal.scheduler_placement.SchedulerPlacement] = None,
         enable_snapshot: bool = False,
         verbose: bool = False,
-    ) -> Sandbox: ...
+    ) -> Sandbox:
+        """mdmd:hidden"""
+        ...
 
     class __create_spec(typing_extensions.Protocol):
         def __call__(
@@ -276,7 +386,21 @@ class Sandbox(modal.object.Object):
             _experimental_enable_snapshot: bool = False,
             _experimental_scheduler_placement: typing.Optional[modal.scheduler_placement.SchedulerPlacement] = None,
             client: typing.Optional[modal.client.Client] = None,
-        ) -> Sandbox: ...
+        ) -> Sandbox:
+            """Create a new Sandbox to run untrusted, arbitrary code. The Sandbox's corresponding container
+            will be created asynchronously.
+
+            **Usage**
+
+            ```python
+            app = modal.App.lookup('sandbox-hello-world', create_if_missing=True)
+            sandbox = modal.Sandbox.create("echo", "hello world", app=app)
+            print(sandbox.stdout.read())
+            sandbox.wait()
+            ```
+            """
+            ...
+
         async def aio(
             self,
             /,
@@ -310,7 +434,20 @@ class Sandbox(modal.object.Object):
             _experimental_enable_snapshot: bool = False,
             _experimental_scheduler_placement: typing.Optional[modal.scheduler_placement.SchedulerPlacement] = None,
             client: typing.Optional[modal.client.Client] = None,
-        ) -> Sandbox: ...
+        ) -> Sandbox:
+            """Create a new Sandbox to run untrusted, arbitrary code. The Sandbox's corresponding container
+            will be created asynchronously.
+
+            **Usage**
+
+            ```python
+            app = modal.App.lookup('sandbox-hello-world', create_if_missing=True)
+            sandbox = modal.Sandbox.create("echo", "hello world", app=app)
+            print(sandbox.stdout.read())
+            sandbox.wait()
+            ```
+            """
+            ...
 
     create: __create_spec
 
@@ -391,44 +528,121 @@ class Sandbox(modal.object.Object):
     def _hydrate_metadata(self, handle_metadata: typing.Optional[google.protobuf.message.Message]): ...
 
     class __from_id_spec(typing_extensions.Protocol):
-        def __call__(self, /, sandbox_id: str, client: typing.Optional[modal.client.Client] = None) -> Sandbox: ...
-        async def aio(self, /, sandbox_id: str, client: typing.Optional[modal.client.Client] = None) -> Sandbox: ...
+        def __call__(self, /, sandbox_id: str, client: typing.Optional[modal.client.Client] = None) -> Sandbox:
+            """Construct a Sandbox from an id and look up the Sandbox result.
+
+            The ID of a Sandbox object can be accessed using `.object_id`.
+            """
+            ...
+
+        async def aio(self, /, sandbox_id: str, client: typing.Optional[modal.client.Client] = None) -> Sandbox:
+            """Construct a Sandbox from an id and look up the Sandbox result.
+
+            The ID of a Sandbox object can be accessed using `.object_id`.
+            """
+            ...
 
     from_id: __from_id_spec
 
     class __set_tags_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, tags: dict[str, str], *, client: typing.Optional[modal.client.Client] = None): ...
-        async def aio(self, /, tags: dict[str, str], *, client: typing.Optional[modal.client.Client] = None): ...
+        def __call__(self, /, tags: dict[str, str], *, client: typing.Optional[modal.client.Client] = None):
+            """Set tags (key-value pairs) on the Sandbox. Tags can be used to filter results in `Sandbox.list`."""
+            ...
+
+        async def aio(self, /, tags: dict[str, str], *, client: typing.Optional[modal.client.Client] = None):
+            """Set tags (key-value pairs) on the Sandbox. Tags can be used to filter results in `Sandbox.list`."""
+            ...
 
     set_tags: __set_tags_spec[typing_extensions.Self]
 
     class __snapshot_filesystem_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, timeout: int = 55) -> modal.image.Image: ...
-        async def aio(self, /, timeout: int = 55) -> modal.image.Image: ...
+        def __call__(self, /, timeout: int = 55) -> modal.image.Image:
+            """Snapshot the filesystem of the Sandbox.
+
+            Returns an [`Image`](https://modal.com/docs/reference/modal.Image) object which
+            can be used to spawn a new Sandbox with the same filesystem.
+            """
+            ...
+
+        async def aio(self, /, timeout: int = 55) -> modal.image.Image:
+            """Snapshot the filesystem of the Sandbox.
+
+            Returns an [`Image`](https://modal.com/docs/reference/modal.Image) object which
+            can be used to spawn a new Sandbox with the same filesystem.
+            """
+            ...
 
     snapshot_filesystem: __snapshot_filesystem_spec[typing_extensions.Self]
 
     class __wait_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, raise_on_termination: bool = True): ...
-        async def aio(self, /, raise_on_termination: bool = True): ...
+        def __call__(self, /, raise_on_termination: bool = True):
+            """Wait for the Sandbox to finish running."""
+            ...
+
+        async def aio(self, /, raise_on_termination: bool = True):
+            """Wait for the Sandbox to finish running."""
+            ...
 
     wait: __wait_spec[typing_extensions.Self]
 
     class __tunnels_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, timeout: int = 50) -> dict[int, modal._tunnel.Tunnel]: ...
-        async def aio(self, /, timeout: int = 50) -> dict[int, modal._tunnel.Tunnel]: ...
+        def __call__(self, /, timeout: int = 50) -> dict[int, modal._tunnel.Tunnel]:
+            """Get Tunnel metadata for the sandbox.
+
+            Raises `SandboxTimeoutError` if the tunnels are not available after the timeout.
+
+            Returns a dictionary of `Tunnel` objects which are keyed by the container port.
+
+            NOTE: Previous to client [v0.64.153](https://modal.com/docs/reference/changelog#064153-2024-09-30), this
+            returned a list of `TunnelData` objects.
+            """
+            ...
+
+        async def aio(self, /, timeout: int = 50) -> dict[int, modal._tunnel.Tunnel]:
+            """Get Tunnel metadata for the sandbox.
+
+            Raises `SandboxTimeoutError` if the tunnels are not available after the timeout.
+
+            Returns a dictionary of `Tunnel` objects which are keyed by the container port.
+
+            NOTE: Previous to client [v0.64.153](https://modal.com/docs/reference/changelog#064153-2024-09-30), this
+            returned a list of `TunnelData` objects.
+            """
+            ...
 
     tunnels: __tunnels_spec[typing_extensions.Self]
 
     class __terminate_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /) -> None: ...
-        async def aio(self, /) -> None: ...
+        def __call__(self, /) -> None:
+            """Terminate Sandbox execution.
+
+            This is a no-op if the Sandbox has already finished running.
+            """
+            ...
+
+        async def aio(self, /) -> None:
+            """Terminate Sandbox execution.
+
+            This is a no-op if the Sandbox has already finished running.
+            """
+            ...
 
     terminate: __terminate_spec[typing_extensions.Self]
 
     class __poll_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /) -> typing.Optional[int]: ...
-        async def aio(self, /) -> typing.Optional[int]: ...
+        def __call__(self, /) -> typing.Optional[int]:
+            """Check if the Sandbox has finished running.
+
+            Returns `None` if the Sandbox is still running, else returns the exit code.
+            """
+            ...
+
+        async def aio(self, /) -> typing.Optional[int]:
+            """Check if the Sandbox has finished running.
+
+            Returns `None` if the Sandbox is still running, else returns the exit code.
+            """
+            ...
 
     poll: __poll_spec[typing_extensions.Self]
 
@@ -531,20 +745,35 @@ class Sandbox(modal.object.Object):
     open: __open_spec[typing_extensions.Self]
 
     class __ls_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, path: str) -> list[str]: ...
-        async def aio(self, /, path: str) -> list[str]: ...
+        def __call__(self, /, path: str) -> list[str]:
+            """List the contents of a directory in the Sandbox."""
+            ...
+
+        async def aio(self, /, path: str) -> list[str]:
+            """List the contents of a directory in the Sandbox."""
+            ...
 
     ls: __ls_spec[typing_extensions.Self]
 
     class __mkdir_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, path: str, parents: bool = False) -> None: ...
-        async def aio(self, /, path: str, parents: bool = False) -> None: ...
+        def __call__(self, /, path: str, parents: bool = False) -> None:
+            """Create a new directory in the Sandbox."""
+            ...
+
+        async def aio(self, /, path: str, parents: bool = False) -> None:
+            """Create a new directory in the Sandbox."""
+            ...
 
     mkdir: __mkdir_spec[typing_extensions.Self]
 
     class __rm_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, path: str, recursive: bool = False) -> None: ...
-        async def aio(self, /, path: str, recursive: bool = False) -> None: ...
+        def __call__(self, /, path: str, recursive: bool = False) -> None:
+            """Remove a file or directory in the Sandbox."""
+            ...
+
+        async def aio(self, /, path: str, recursive: bool = False) -> None:
+            """Remove a file or directory in the Sandbox."""
+            ...
 
     rm: __rm_spec[typing_extensions.Self]
 
@@ -556,7 +785,10 @@ class Sandbox(modal.object.Object):
             filter: typing.Optional[list[modal.file_io.FileWatchEventType]] = None,
             recursive: typing.Optional[bool] = None,
             timeout: typing.Optional[int] = None,
-        ) -> typing.Iterator[modal.file_io.FileWatchEvent]: ...
+        ) -> typing.Iterator[modal.file_io.FileWatchEvent]:
+            """Watch a file or directory in the Sandbox for changes."""
+            ...
+
         def aio(
             self,
             /,
@@ -564,18 +796,37 @@ class Sandbox(modal.object.Object):
             filter: typing.Optional[list[modal.file_io.FileWatchEventType]] = None,
             recursive: typing.Optional[bool] = None,
             timeout: typing.Optional[int] = None,
-        ) -> typing.AsyncIterator[modal.file_io.FileWatchEvent]: ...
+        ) -> typing.AsyncIterator[modal.file_io.FileWatchEvent]:
+            """Watch a file or directory in the Sandbox for changes."""
+            ...
 
     watch: __watch_spec[typing_extensions.Self]
 
     @property
-    def stdout(self) -> modal.io_streams.StreamReader[str]: ...
+    def stdout(self) -> modal.io_streams.StreamReader[str]:
+        """[`StreamReader`](https://modal.com/docs/reference/modal.io_streams#modalio_streamsstreamreader) for
+        the sandbox's stdout stream.
+        """
+        ...
+
     @property
-    def stderr(self) -> modal.io_streams.StreamReader[str]: ...
+    def stderr(self) -> modal.io_streams.StreamReader[str]:
+        """[`StreamReader`](https://modal.com/docs/reference/modal.io_streams#modalio_streamsstreamreader) for
+        the Sandbox's stderr stream.
+        """
+        ...
+
     @property
-    def stdin(self) -> modal.io_streams.StreamWriter: ...
+    def stdin(self) -> modal.io_streams.StreamWriter:
+        """[`StreamWriter`](https://modal.com/docs/reference/modal.io_streams#modalio_streamsstreamwriter) for
+        the Sandbox's stdin stream.
+        """
+        ...
+
     @property
-    def returncode(self) -> typing.Optional[int]: ...
+    def returncode(self) -> typing.Optional[int]:
+        """Return code of the Sandbox process if it has finished running, else `None`."""
+        ...
 
     class __list_spec(typing_extensions.Protocol):
         def __call__(
@@ -585,7 +836,12 @@ class Sandbox(modal.object.Object):
             app_id: typing.Optional[str] = None,
             tags: typing.Optional[dict[str, str]] = None,
             client: typing.Optional[modal.client.Client] = None,
-        ) -> typing.Generator[Sandbox, None, None]: ...
+        ) -> typing.Generator[Sandbox, None, None]:
+            """List all Sandboxes for the current Environment or App ID (if specified). If tags are specified, only
+            Sandboxes that have at least those tags are returned. Returns an iterator over `Sandbox` objects.
+            """
+            ...
+
         def aio(
             self,
             /,
@@ -593,7 +849,11 @@ class Sandbox(modal.object.Object):
             app_id: typing.Optional[str] = None,
             tags: typing.Optional[dict[str, str]] = None,
             client: typing.Optional[modal.client.Client] = None,
-        ) -> collections.abc.AsyncGenerator[Sandbox, None]: ...
+        ) -> collections.abc.AsyncGenerator[Sandbox, None]:
+            """List all Sandboxes for the current Environment or App ID (if specified). If tags are specified, only
+            Sandboxes that have at least those tags are returned. Returns an iterator over `Sandbox` objects.
+            """
+            ...
 
     list: __list_spec
 

modal/schedule.py

@@ -13,7 +13,7 @@ class Cron(Schedule):
     """Cron jobs are a type of schedule, specified using the
     [Unix cron tab](https://crontab.guru/) syntax.
 
-    The alternative schedule type is the [`modal.Period`](/docs/reference/modal.Period).
+    The alternative schedule type is the [`modal.Period`](https://modal.com/docs/reference/modal.Period).
 
     **Usage**
 

modal/secret.py

@@ -24,9 +24,9 @@ class _Secret(_Object, type_prefix="st"):
 
     Secrets are a secure way to add credentials and other sensitive information
     to the containers your functions run in. You can create and edit secrets on
-    [the dashboard](/secrets), or programmatically from Python code.
+    [the dashboard](https://modal.com/secrets), or programmatically from Python code.
 
-    See [the secrets guide page](/docs/guide/secrets) for more information.
+    See [the secrets guide page](https://modal.com/docs/guide/secrets) for more information.
     """
 
     @staticmethod