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

modal/secret.pyi

@@ -5,16 +5,82 @@ import typing
 import typing_extensions
 
 class _Secret(modal._object._Object):
+    """Secrets provide a dictionary of environment variables for images.
+
+    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](https://modal.com/secrets), or programmatically from Python code.
+
+    See [the secrets guide page](https://modal.com/docs/guide/secrets) for more information.
+    """
     @staticmethod
-    def from_dict(env_dict: dict[str, typing.Optional[str]] = {}) -> _Secret: ...
+    def from_dict(env_dict: dict[str, typing.Optional[str]] = {}) -> _Secret:
+        """Create a secret from a str-str dictionary. Values can also be `None`, which is ignored.
+
+        Usage:
+        ```python
+        @app.function(secrets=[modal.Secret.from_dict({"FOO": "bar"})])
+        def run():
+            print(os.environ["FOO"])
+        ```
+        """
+        ...
+
     @staticmethod
-    def from_local_environ(env_keys: list[str]) -> _Secret: ...
+    def from_local_environ(env_keys: list[str]) -> _Secret:
+        """Create secrets from local environment variables automatically."""
+        ...
+
     @staticmethod
-    def from_dotenv(path=None, *, filename=".env") -> _Secret: ...
+    def from_dotenv(path=None, *, filename=".env") -> _Secret:
+        """Create secrets from a .env file automatically.
+
+        If no argument is provided, it will use the current working directory as the starting
+        point for finding a `.env` file. Note that it does not use the location of the module
+        calling `Secret.from_dotenv`.
+
+        If called with an argument, it will use that as a starting point for finding `.env` files.
+        In particular, you can call it like this:
+        ```python
+        @app.function(secrets=[modal.Secret.from_dotenv(__file__)])
+        def run():
+            print(os.environ["USERNAME"])  # Assumes USERNAME is defined in your .env file
+        ```
+
+        This will use the location of the script calling `modal.Secret.from_dotenv` as a
+        starting point for finding the `.env` file.
+
+        A file named `.env` is expected by default, but this can be overridden with the `filename`
+        keyword argument:
+
+        ```python
+        @app.function(secrets=[modal.Secret.from_dotenv(filename=".env-dev")])
+        def run():
+            ...
+        ```
+        """
+        ...
+
     @staticmethod
     def from_name(
         name: str, *, namespace=1, environment_name: typing.Optional[str] = None, required_keys: list[str] = []
-    ) -> _Secret: ...
+    ) -> _Secret:
+        """Reference a Secret by its name.
+
+        In contrast to most other Modal objects, named Secrets must be provisioned
+        from the Dashboard. See other methods for alternate ways of creating a new
+        Secret from code.
+
+        ```python
+        secret = modal.Secret.from_name("my-secret")
+
+        @app.function(secrets=[secret])
+        def run():
+           ...
+        ```
+        """
+        ...
+
     @staticmethod
     async def lookup(
         name: str,
@@ -22,7 +88,10 @@ class _Secret(modal._object._Object):
         client: typing.Optional[modal.client._Client] = None,
         environment_name: typing.Optional[str] = None,
         required_keys: list[str] = [],
-    ) -> _Secret: ...
+    ) -> _Secret:
+        """mdmd:hidden"""
+        ...
+
     @staticmethod
     async def create_deployed(
         deployment_name: str,
@@ -31,20 +100,90 @@ class _Secret(modal._object._Object):
         client: typing.Optional[modal.client._Client] = None,
         environment_name: typing.Optional[str] = None,
         overwrite: bool = False,
-    ) -> str: ...
+    ) -> str:
+        """mdmd:hidden"""
+        ...
 
 class Secret(modal.object.Object):
-    def __init__(self, *args, **kwargs): ...
+    """Secrets provide a dictionary of environment variables for images.
+
+    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](https://modal.com/secrets), or programmatically from Python code.
+
+    See [the secrets guide page](https://modal.com/docs/guide/secrets) for more information.
+    """
+    def __init__(self, *args, **kwargs):
+        """mdmd:hidden"""
+        ...
+
     @staticmethod
-    def from_dict(env_dict: dict[str, typing.Optional[str]] = {}) -> Secret: ...
+    def from_dict(env_dict: dict[str, typing.Optional[str]] = {}) -> Secret:
+        """Create a secret from a str-str dictionary. Values can also be `None`, which is ignored.
+
+        Usage:
+        ```python
+        @app.function(secrets=[modal.Secret.from_dict({"FOO": "bar"})])
+        def run():
+            print(os.environ["FOO"])
+        ```
+        """
+        ...
+
     @staticmethod
-    def from_local_environ(env_keys: list[str]) -> Secret: ...
+    def from_local_environ(env_keys: list[str]) -> Secret:
+        """Create secrets from local environment variables automatically."""
+        ...
+
     @staticmethod
-    def from_dotenv(path=None, *, filename=".env") -> Secret: ...
+    def from_dotenv(path=None, *, filename=".env") -> Secret:
+        """Create secrets from a .env file automatically.
+
+        If no argument is provided, it will use the current working directory as the starting
+        point for finding a `.env` file. Note that it does not use the location of the module
+        calling `Secret.from_dotenv`.
+
+        If called with an argument, it will use that as a starting point for finding `.env` files.
+        In particular, you can call it like this:
+        ```python
+        @app.function(secrets=[modal.Secret.from_dotenv(__file__)])
+        def run():
+            print(os.environ["USERNAME"])  # Assumes USERNAME is defined in your .env file
+        ```
+
+        This will use the location of the script calling `modal.Secret.from_dotenv` as a
+        starting point for finding the `.env` file.
+
+        A file named `.env` is expected by default, but this can be overridden with the `filename`
+        keyword argument:
+
+        ```python
+        @app.function(secrets=[modal.Secret.from_dotenv(filename=".env-dev")])
+        def run():
+            ...
+        ```
+        """
+        ...
+
     @staticmethod
     def from_name(
         name: str, *, namespace=1, environment_name: typing.Optional[str] = None, required_keys: list[str] = []
-    ) -> Secret: ...
+    ) -> Secret:
+        """Reference a Secret by its name.
+
+        In contrast to most other Modal objects, named Secrets must be provisioned
+        from the Dashboard. See other methods for alternate ways of creating a new
+        Secret from code.
+
+        ```python
+        secret = modal.Secret.from_name("my-secret")
+
+        @app.function(secrets=[secret])
+        def run():
+           ...
+        ```
+        """
+        ...
 
     class __lookup_spec(typing_extensions.Protocol):
         def __call__(
@@ -55,7 +194,10 @@ class Secret(modal.object.Object):
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
             required_keys: list[str] = [],
-        ) -> Secret: ...
+        ) -> Secret:
+            """mdmd:hidden"""
+            ...
+
         async def aio(
             self,
             /,
@@ -64,7 +206,9 @@ class Secret(modal.object.Object):
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
             required_keys: list[str] = [],
-        ) -> Secret: ...
+        ) -> Secret:
+            """mdmd:hidden"""
+            ...
 
     lookup: __lookup_spec
 
@@ -78,7 +222,10 @@ class Secret(modal.object.Object):
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
             overwrite: bool = False,
-        ) -> str: ...
+        ) -> str:
+            """mdmd:hidden"""
+            ...
+
         async def aio(
             self,
             /,
@@ -88,6 +235,8 @@ class Secret(modal.object.Object):
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
             overwrite: bool = False,
-        ) -> str: ...
+        ) -> str:
+            """mdmd:hidden"""
+            ...
 
     create_deployed: __create_deployed_spec

modal/snapshot.pyi

@@ -5,14 +5,35 @@ import typing
 import typing_extensions
 
 class _SandboxSnapshot(modal._object._Object):
+    """> Sandbox memory snapshots are in **early preview**.
+
+    A `SandboxSnapshot` object lets you interact with a stored Sandbox snapshot that was created by calling
+    `._experimental_snapshot()` on a Sandbox instance. This includes both the filesystem and memory state of
+    the original Sandbox at the time the snapshot was taken.
+    """
     @staticmethod
-    async def from_id(sandbox_snapshot_id: str, client: typing.Optional[modal.client._Client] = None): ...
+    async def from_id(sandbox_snapshot_id: str, client: typing.Optional[modal.client._Client] = None):
+        """Construct a `SandboxSnapshot` object from a sandbox snapshot ID."""
+        ...
 
 class SandboxSnapshot(modal.object.Object):
-    def __init__(self, *args, **kwargs): ...
+    """> Sandbox memory snapshots are in **early preview**.
+
+    A `SandboxSnapshot` object lets you interact with a stored Sandbox snapshot that was created by calling
+    `._experimental_snapshot()` on a Sandbox instance. This includes both the filesystem and memory state of
+    the original Sandbox at the time the snapshot was taken.
+    """
+    def __init__(self, *args, **kwargs):
+        """mdmd:hidden"""
+        ...
 
     class __from_id_spec(typing_extensions.Protocol):
-        def __call__(self, /, sandbox_snapshot_id: str, client: typing.Optional[modal.client.Client] = None): ...
-        async def aio(self, /, sandbox_snapshot_id: str, client: typing.Optional[modal.client.Client] = None): ...
+        def __call__(self, /, sandbox_snapshot_id: str, client: typing.Optional[modal.client.Client] = None):
+            """Construct a `SandboxSnapshot` object from a sandbox snapshot ID."""
+            ...
+
+        async def aio(self, /, sandbox_snapshot_id: str, client: typing.Optional[modal.client.Client] = None):
+            """Construct a `SandboxSnapshot` object from a sandbox snapshot ID."""
+            ...
 
     from_id: __from_id_spec

modal/token_flow.pyi

@@ -5,13 +5,21 @@ import typing
 import typing_extensions
 
 class _TokenFlow:
-    def __init__(self, client: modal.client._Client): ...
+    def __init__(self, client: modal.client._Client):
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
     def start(
         self, utm_source: typing.Optional[str] = None, next_url: typing.Optional[str] = None
-    ) -> typing.AsyncContextManager[tuple[str, str, str]]: ...
+    ) -> typing.AsyncContextManager[tuple[str, str, str]]:
+        """mdmd:hidden"""
+        ...
+
     async def finish(
         self, timeout: float = 40.0, grpc_extra_timeout: float = 5.0
-    ) -> typing.Optional[modal_proto.api_pb2.TokenFlowWaitResponse]: ...
+    ) -> typing.Optional[modal_proto.api_pb2.TokenFlowWaitResponse]:
+        """mdmd:hidden"""
+        ...
 
 SUPERSELF = typing.TypeVar("SUPERSELF", covariant=True)
 
@@ -21,20 +29,30 @@ class TokenFlow:
     class __start_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(
             self, /, utm_source: typing.Optional[str] = None, next_url: typing.Optional[str] = None
-        ) -> synchronicity.combined_types.AsyncAndBlockingContextManager[tuple[str, str, str]]: ...
+        ) -> synchronicity.combined_types.AsyncAndBlockingContextManager[tuple[str, str, str]]:
+            """mdmd:hidden"""
+            ...
+
         def aio(
             self, /, utm_source: typing.Optional[str] = None, next_url: typing.Optional[str] = None
-        ) -> typing.AsyncContextManager[tuple[str, str, str]]: ...
+        ) -> typing.AsyncContextManager[tuple[str, str, str]]:
+            """mdmd:hidden"""
+            ...
 
     start: __start_spec[typing_extensions.Self]
 
     class __finish_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(
             self, /, timeout: float = 40.0, grpc_extra_timeout: float = 5.0
-        ) -> typing.Optional[modal_proto.api_pb2.TokenFlowWaitResponse]: ...
+        ) -> typing.Optional[modal_proto.api_pb2.TokenFlowWaitResponse]:
+            """mdmd:hidden"""
+            ...
+
         async def aio(
             self, /, timeout: float = 40.0, grpc_extra_timeout: float = 5.0
-        ) -> typing.Optional[modal_proto.api_pb2.TokenFlowWaitResponse]: ...
+        ) -> typing.Optional[modal_proto.api_pb2.TokenFlowWaitResponse]:
+            """mdmd:hidden"""
+            ...
 
     finish: __finish_spec[typing_extensions.Self]
 
@@ -55,4 +73,6 @@ async def _set_token(
     verify: bool = True,
     server_url: typing.Optional[str] = None,
 ): ...
-def _open_url(url: str) -> bool: ...
+def _open_url(url: str) -> bool:
+    """Opens url in web browser, making sure we use a modern one (not Lynx etc)"""
+    ...

modal/volume.py

@@ -135,6 +135,34 @@ class _Volume(_Object, type_prefix="vo"):
 
     _lock: Optional[asyncio.Lock] = None
     _metadata: "typing.Optional[api_pb2.VolumeMetadata]"
+    _read_only: bool = False
+
+    def read_only(self) -> "_Volume":
+        """Configure Volume to mount as read-only.
+
+        **Example**
+
+        ```python
+        import modal
+
+        volume = modal.Volume.from_name("my-volume", create_if_missing=True)
+
+        @app.function(volumes={"/mnt/items": volume.read_only()})
+        def f():
+            with open("/mnt/items/my-file.txt") as f:
+                return f.read()
+        ```
+
+        The Volume is mounted as a read-only volume in a function. Any file system write operation into the
+        mounted volume will result in an error.
+        """
+
+        async def _load(new_volume: _Volume, resolver: Resolver, existing_object_id: Optional[str]):
+            new_volume._initialize_from_other(self)
+            new_volume._read_only = True
+
+        obj = _Volume._from_loader(_load, "Volume()", hydrate_lazily=True, deps=lambda: [self])
+        return obj
 
     async def _get_lock(self):
         # To (mostly*) prevent multiple concurrent operations on the same volume, which can cause problems under
@@ -161,9 +189,9 @@ class _Volume(_Object, type_prefix="vo"):
     ) -> "_Volume":
         """Reference a Volume by name, creating if necessary.
 
-        In contrast to `modal.Volume.lookup`, this is a lazy method
-        that defers hydrating the local object with metadata from
-        Modal servers until the first time is is actually used.
+        This is a lazy method that defers hydrating the local
+        object with metadata from Modal servers until the first
+        time is is actually used.
 
         ```python
         vol = modal.Volume.from_name("my-volume", create_if_missing=True)
@@ -405,7 +433,7 @@ class _Volume(_Object, type_prefix="vo"):
 
         Note - this function is primarily intended to be used outside of a Modal App.
         For more information on downloading files from a Modal Volume, see
-        [the guide](/docs/guide/volumes).
+        [the guide](https://modal.com/docs/guide/volumes).
 
         **Example:**
 
@@ -495,6 +523,9 @@ class _Volume(_Object, type_prefix="vo"):
     @live_method
     async def remove_file(self, path: str, recursive: bool = False) -> None:
         """Remove a file or directory from a volume."""
+        if self._read_only:
+            raise InvalidError("Read-only Volume can not be written to")
+
         if self._is_v1:
             req = api_pb2.VolumeRemoveFileRequest(volume_id=self.object_id, path=path, recursive=recursive)
             await retry_transient_errors(self._client.stub.VolumeRemoveFile, req)
@@ -527,6 +558,9 @@ class _Volume(_Object, type_prefix="vo"):
         like `os.rename()` and then `commit()` the volume. The `copy_files()` method is useful when you don't have
         the volume mounted as a filesystem, e.g. when running a script on your local computer.
         """
+        if self._read_only:
+            raise InvalidError("Read-only Volume can not be written to")
+
         if self._is_v1:
             if recursive:
                 raise ValueError("`recursive` is not supported for V1 volumes")
@@ -560,6 +594,9 @@ class _Volume(_Object, type_prefix="vo"):
             batch.put_file(io.BytesIO(b"some data"), "/foobar")
         ```
         """
+        if self._read_only:
+            raise InvalidError("Read-only Volume can not be written to")
+
         return _AbstractVolumeUploadContextManager.resolve(
             self._metadata.version, self.object_id, self._client, force=force
         )