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

modal/client.pyi

@@ -31,28 +31,94 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.0.5.dev2",
-    ): ...
+        version: str = "1.0.5.dev3",
+    ):
+        """mdmd:hidden
+        The Modal client object is not intended to be instantiated directly by users.
+        """
+        ...
+
     def is_closed(self) -> bool: ...
     @property
-    def stub(self) -> modal_proto.modal_api_grpc.ModalClientModal: ...
-    async def get_stub(self, server_url: str) -> modal_proto.modal_api_grpc.ModalClientModal: ...
+    def stub(self) -> modal_proto.modal_api_grpc.ModalClientModal:
+        """mdmd:hidden
+        The default stub. Stubs can safely be used across forks / client snapshots.
+
+        This is useful if you want to make requests to the default Modal server in us-east, for example
+        control plane requests.
+
+        This is equivalent to client.get_stub(default_server_url), but it's cached, so it's a bit faster.
+        """
+        ...
+
+    async def get_stub(self, server_url: str) -> modal_proto.modal_api_grpc.ModalClientModal:
+        """mdmd:hidden
+        Get a stub for a specific server URL. Stubs can safely be used across forks / client snapshots.
+
+        This is useful if you want to make requests to a regional Modal server, for example low-latency
+        function calls in us-west.
+
+        This function is O(n) where n is the number of RPCs in ModalClient.
+        """
+        ...
+
     async def _open(self): ...
     async def _close(self, prep_for_restore: bool = False): ...
-    async def hello(self): ...
+    async def hello(self):
+        """Connect to server and retrieve version information; raise appropriate error for various failures."""
+        ...
+
     async def __aenter__(self): ...
     async def __aexit__(self, exc_type, exc, tb): ...
     @classmethod
-    def anonymous(cls, server_url: str) -> typing.AsyncContextManager[_Client]: ...
+    def anonymous(cls, server_url: str) -> typing.AsyncContextManager[_Client]:
+        """mdmd:hidden
+        Create a connection with no credentials; to be used for token creation.
+        """
+        ...
+
     @classmethod
-    async def from_env(cls, _override_config=None) -> _Client: ...
+    async def from_env(cls, _override_config=None) -> _Client:
+        """mdmd:hidden
+        Singleton that is instantiated from the Modal config and reused on subsequent calls.
+        """
+        ...
+
     @classmethod
-    async def from_credentials(cls, token_id: str, token_secret: str) -> _Client: ...
+    async def from_credentials(cls, token_id: str, token_secret: str) -> _Client:
+        """Constructor based on token credentials; useful for managing Modal on behalf of third-party users.
+
+        **Usage:**
+
+        ```python notest
+        client = modal.Client.from_credentials("my_token_id", "my_token_secret")
+
+        modal.Sandbox.create("echo", "hi", client=client, app=app)
+        ```
+        """
+        ...
+
     @classmethod
-    async def verify(cls, server_url: str, credentials: tuple[str, str]) -> None: ...
+    async def verify(cls, server_url: str, credentials: tuple[str, str]) -> None:
+        """mdmd:hidden
+        Check whether can the client can connect to this server with these credentials; raise if not.
+        """
+        ...
+
     @classmethod
-    def set_env_client(cls, client: typing.Optional[_Client]): ...
-    async def _call_safely(self, coro, readable_method: str): ...
+    def set_env_client(cls, client: typing.Optional[_Client]):
+        """mdmd:hidden"""
+        ...
+
+    async def _call_safely(self, coro, readable_method: str):
+        """Runs coroutine wrapped in a task that's part of the client's task context
+
+        * Raises ClientClosed in case the client is closed while the coroutine is executed
+        * Logs warning if call is made outside of the event loop that the client is running in,
+          and execute without the cancellation context in that case
+        """
+        ...
+
     async def _reset_on_pid_change(self): ...
     async def _get_channel(self, server_url: str) -> grpclib.client.Channel: ...
     async def _call_unary(
@@ -94,15 +160,48 @@ class Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.0.5.dev2",
-    ): ...
+        version: str = "1.0.5.dev3",
+    ):
+        """mdmd:hidden
+        The Modal client object is not intended to be instantiated directly by users.
+        """
+        ...
+
     def is_closed(self) -> bool: ...
     @property
-    def stub(self) -> modal_proto.modal_api_grpc.ModalClientModal: ...
+    def stub(self) -> modal_proto.modal_api_grpc.ModalClientModal:
+        """mdmd:hidden
+        The default stub. Stubs can safely be used across forks / client snapshots.
+
+        This is useful if you want to make requests to the default Modal server in us-east, for example
+        control plane requests.
+
+        This is equivalent to client.get_stub(default_server_url), but it's cached, so it's a bit faster.
+        """
+        ...
 
     class __get_stub_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, server_url: str) -> modal_proto.modal_api_grpc.ModalClientModal: ...
-        async def aio(self, /, server_url: str) -> modal_proto.modal_api_grpc.ModalClientModal: ...
+        def __call__(self, /, server_url: str) -> modal_proto.modal_api_grpc.ModalClientModal:
+            """mdmd:hidden
+            Get a stub for a specific server URL. Stubs can safely be used across forks / client snapshots.
+
+            This is useful if you want to make requests to a regional Modal server, for example low-latency
+            function calls in us-west.
+
+            This function is O(n) where n is the number of RPCs in ModalClient.
+            """
+            ...
+
+        async def aio(self, /, server_url: str) -> modal_proto.modal_api_grpc.ModalClientModal:
+            """mdmd:hidden
+            Get a stub for a specific server URL. Stubs can safely be used across forks / client snapshots.
+
+            This is useful if you want to make requests to a regional Modal server, for example low-latency
+            function calls in us-west.
+
+            This function is O(n) where n is the number of RPCs in ModalClient.
+            """
+            ...
 
     get_stub: __get_stub_spec[typing_extensions.Self]
 
@@ -119,8 +218,13 @@ class Client:
     _close: ___close_spec[typing_extensions.Self]
 
     class __hello_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /): ...
-        async def aio(self, /): ...
+        def __call__(self, /):
+            """Connect to server and retrieve version information; raise appropriate error for various failures."""
+            ...
+
+        async def aio(self, /):
+            """Connect to server and retrieve version information; raise appropriate error for various failures."""
+            ...
 
     hello: __hello_spec[typing_extensions.Self]
 
@@ -129,19 +233,63 @@ class Client:
     def __exit__(self, exc_type, exc, tb): ...
     async def __aexit__(self, exc_type, exc, tb): ...
     @classmethod
-    def anonymous(cls, server_url: str) -> synchronicity.combined_types.AsyncAndBlockingContextManager[Client]: ...
+    def anonymous(cls, server_url: str) -> synchronicity.combined_types.AsyncAndBlockingContextManager[Client]:
+        """mdmd:hidden
+        Create a connection with no credentials; to be used for token creation.
+        """
+        ...
+
     @classmethod
-    def from_env(cls, _override_config=None) -> Client: ...
+    def from_env(cls, _override_config=None) -> Client:
+        """mdmd:hidden
+        Singleton that is instantiated from the Modal config and reused on subsequent calls.
+        """
+        ...
+
     @classmethod
-    def from_credentials(cls, token_id: str, token_secret: str) -> Client: ...
+    def from_credentials(cls, token_id: str, token_secret: str) -> Client:
+        """Constructor based on token credentials; useful for managing Modal on behalf of third-party users.
+
+        **Usage:**
+
+        ```python notest
+        client = modal.Client.from_credentials("my_token_id", "my_token_secret")
+
+        modal.Sandbox.create("echo", "hi", client=client, app=app)
+        ```
+        """
+        ...
+
     @classmethod
-    def verify(cls, server_url: str, credentials: tuple[str, str]) -> None: ...
+    def verify(cls, server_url: str, credentials: tuple[str, str]) -> None:
+        """mdmd:hidden
+        Check whether can the client can connect to this server with these credentials; raise if not.
+        """
+        ...
+
     @classmethod
-    def set_env_client(cls, client: typing.Optional[Client]): ...
+    def set_env_client(cls, client: typing.Optional[Client]):
+        """mdmd:hidden"""
+        ...
 
     class ___call_safely_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, coro, readable_method: str): ...
-        async def aio(self, /, coro, readable_method: str): ...
+        def __call__(self, /, coro, readable_method: str):
+            """Runs coroutine wrapped in a task that's part of the client's task context
+
+            * Raises ClientClosed in case the client is closed while the coroutine is executed
+            * Logs warning if call is made outside of the event loop that the client is running in,
+              and execute without the cancellation context in that case
+            """
+            ...
+
+        async def aio(self, /, coro, readable_method: str):
+            """Runs coroutine wrapped in a task that's part of the client's task context
+
+            * Raises ClientClosed in case the client is closed while the coroutine is executed
+            * Logs warning if call is made outside of the event loop that the client is running in,
+              and execute without the cancellation context in that case
+            """
+            ...
 
     _call_safely: ___call_safely_spec[typing_extensions.Self]
 
@@ -182,6 +330,26 @@ class Client:
     ) -> collections.abc.AsyncGenerator[typing.Any, None]: ...
 
 class UnaryUnaryWrapper(typing.Generic[RequestType, ResponseType]):
+    """Abstract base class for generic types.
+
+    A generic type is typically declared by inheriting from
+    this class parameterized with one or more type variables.
+    For example, a generic mapping type might be defined as::
+
+      class Mapping(Generic[KT, VT]):
+          def __getitem__(self, key: KT) -> VT:
+              ...
+          # Etc.
+
+    This class can then be used as follows::
+
+      def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
+          try:
+              return mapping[key]
+          except KeyError:
+              return default
+    """
+
     wrapped_method: grpclib.client.UnaryUnaryMethod[RequestType, ResponseType]
     client: _Client
 
@@ -190,7 +358,10 @@ class UnaryUnaryWrapper(typing.Generic[RequestType, ResponseType]):
         wrapped_method: grpclib.client.UnaryUnaryMethod[RequestType, ResponseType],
         client: _Client,
         server_url: str,
-    ): ...
+    ):
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
     @property
     def name(self) -> str: ...
     async def __call__(
@@ -203,9 +374,31 @@ class UnaryUnaryWrapper(typing.Generic[RequestType, ResponseType]):
             collections.abc.Collection[tuple[str, typing.Union[str, bytes]]],
             None,
         ] = None,
-    ) -> ResponseType: ...
+    ) -> ResponseType:
+        """Call self as a function."""
+        ...
 
 class UnaryStreamWrapper(typing.Generic[RequestType, ResponseType]):
+    """Abstract base class for generic types.
+
+    A generic type is typically declared by inheriting from
+    this class parameterized with one or more type variables.
+    For example, a generic mapping type might be defined as::
+
+      class Mapping(Generic[KT, VT]):
+          def __getitem__(self, key: KT) -> VT:
+              ...
+          # Etc.
+
+    This class can then be used as follows::
+
+      def lookup_name(mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
+          try:
+              return mapping[key]
+          except KeyError:
+              return default
+    """
+
     wrapped_method: grpclib.client.UnaryStreamMethod[RequestType, ResponseType]
 
     def __init__(
@@ -213,7 +406,10 @@ class UnaryStreamWrapper(typing.Generic[RequestType, ResponseType]):
         wrapped_method: grpclib.client.UnaryStreamMethod[RequestType, ResponseType],
         client: _Client,
         server_url: str,
-    ): ...
+    ):
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
     @property
     def name(self) -> str: ...
     def unary_stream(self, request, metadata: typing.Optional[typing.Any] = None): ...

modal/cloud_bucket_mount.pyi

@@ -3,6 +3,95 @@ import modal_proto.api_pb2
 import typing
 
 class _CloudBucketMount:
+    """Mounts a cloud bucket to your container. Currently supports AWS S3 buckets.
+
+    S3 buckets are mounted using [AWS S3 Mountpoint](https://github.com/awslabs/mountpoint-s3).
+    S3 mounts are optimized for reading large files sequentially. It does not support every file operation; consult
+    [the AWS S3 Mountpoint documentation](https://github.com/awslabs/mountpoint-s3/blob/main/doc/SEMANTICS.md)
+    for more information.
+
+    **AWS S3 Usage**
+
+    ```python
+    import subprocess
+
+    app = modal.App()
+    secret = modal.Secret.from_name(
+        "aws-secret",
+        required_keys=["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"]
+        # Note: providing AWS_REGION can help when automatic detection of the bucket region fails.
+    )
+
+    @app.function(
+        volumes={
+            "/my-mount": modal.CloudBucketMount(
+                bucket_name="s3-bucket-name",
+                secret=secret,
+                read_only=True
+            )
+        }
+    )
+    def f():
+        subprocess.run(["ls", "/my-mount"], check=True)
+    ```
+
+    **Cloudflare R2 Usage**
+
+    Cloudflare R2 is [S3-compatible](https://developers.cloudflare.com/r2/api/s3/api/) so its setup looks
+    very similar to S3. But additionally the `bucket_endpoint_url` argument must be passed.
+
+    ```python
+    import subprocess
+
+    app = modal.App()
+    secret = modal.Secret.from_name(
+        "r2-secret",
+        required_keys=["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"]
+    )
+
+    @app.function(
+        volumes={
+            "/my-mount": modal.CloudBucketMount(
+                bucket_name="my-r2-bucket",
+                bucket_endpoint_url="https://<ACCOUNT ID>.r2.cloudflarestorage.com",
+                secret=secret,
+                read_only=True
+            )
+        }
+    )
+    def f():
+        subprocess.run(["ls", "/my-mount"], check=True)
+    ```
+
+    **Google GCS Usage**
+
+    Google Cloud Storage (GCS) is [S3-compatible](https://cloud.google.com/storage/docs/interoperability).
+    GCS Buckets also require a secret with Google-specific key names (see below) populated with
+    a [HMAC key](https://cloud.google.com/storage/docs/authentication/managing-hmackeys#create).
+
+    ```python
+    import subprocess
+
+    app = modal.App()
+    gcp_hmac_secret = modal.Secret.from_name(
+        "gcp-secret",
+        required_keys=["GOOGLE_ACCESS_KEY_ID", "GOOGLE_ACCESS_KEY_SECRET"]
+    )
+
+    @app.function(
+        volumes={
+            "/my-mount": modal.CloudBucketMount(
+                bucket_name="my-gcs-bucket",
+                bucket_endpoint_url="https://storage.googleapis.com",
+                secret=gcp_hmac_secret,
+            )
+        }
+    )
+    def f():
+        subprocess.run(["ls", "/my-mount"], check=True)
+    ```
+    """
+
     bucket_name: str
     bucket_endpoint_url: typing.Optional[str]
     key_prefix: typing.Optional[str]
@@ -20,15 +109,114 @@ class _CloudBucketMount:
         oidc_auth_role_arn: typing.Optional[str] = None,
         read_only: bool = False,
         requester_pays: bool = False,
-    ) -> None: ...
-    def __repr__(self): ...
-    def __eq__(self, other): ...
+    ) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    def __repr__(self):
+        """Return repr(self)."""
+        ...
+
+    def __eq__(self, other):
+        """Return self==value."""
+        ...
 
 def cloud_bucket_mounts_to_proto(
     mounts: list[tuple[str, _CloudBucketMount]],
-) -> list[modal_proto.api_pb2.CloudBucketMount]: ...
+) -> list[modal_proto.api_pb2.CloudBucketMount]:
+    """Helper function to convert `CloudBucketMount` to a list of protobufs that can be passed to the server."""
+    ...
 
 class CloudBucketMount:
+    """Mounts a cloud bucket to your container. Currently supports AWS S3 buckets.
+
+    S3 buckets are mounted using [AWS S3 Mountpoint](https://github.com/awslabs/mountpoint-s3).
+    S3 mounts are optimized for reading large files sequentially. It does not support every file operation; consult
+    [the AWS S3 Mountpoint documentation](https://github.com/awslabs/mountpoint-s3/blob/main/doc/SEMANTICS.md)
+    for more information.
+
+    **AWS S3 Usage**
+
+    ```python
+    import subprocess
+
+    app = modal.App()
+    secret = modal.Secret.from_name(
+        "aws-secret",
+        required_keys=["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"]
+        # Note: providing AWS_REGION can help when automatic detection of the bucket region fails.
+    )
+
+    @app.function(
+        volumes={
+            "/my-mount": modal.CloudBucketMount(
+                bucket_name="s3-bucket-name",
+                secret=secret,
+                read_only=True
+            )
+        }
+    )
+    def f():
+        subprocess.run(["ls", "/my-mount"], check=True)
+    ```
+
+    **Cloudflare R2 Usage**
+
+    Cloudflare R2 is [S3-compatible](https://developers.cloudflare.com/r2/api/s3/api/) so its setup looks
+    very similar to S3. But additionally the `bucket_endpoint_url` argument must be passed.
+
+    ```python
+    import subprocess
+
+    app = modal.App()
+    secret = modal.Secret.from_name(
+        "r2-secret",
+        required_keys=["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"]
+    )
+
+    @app.function(
+        volumes={
+            "/my-mount": modal.CloudBucketMount(
+                bucket_name="my-r2-bucket",
+                bucket_endpoint_url="https://<ACCOUNT ID>.r2.cloudflarestorage.com",
+                secret=secret,
+                read_only=True
+            )
+        }
+    )
+    def f():
+        subprocess.run(["ls", "/my-mount"], check=True)
+    ```
+
+    **Google GCS Usage**
+
+    Google Cloud Storage (GCS) is [S3-compatible](https://cloud.google.com/storage/docs/interoperability).
+    GCS Buckets also require a secret with Google-specific key names (see below) populated with
+    a [HMAC key](https://cloud.google.com/storage/docs/authentication/managing-hmackeys#create).
+
+    ```python
+    import subprocess
+
+    app = modal.App()
+    gcp_hmac_secret = modal.Secret.from_name(
+        "gcp-secret",
+        required_keys=["GOOGLE_ACCESS_KEY_ID", "GOOGLE_ACCESS_KEY_SECRET"]
+    )
+
+    @app.function(
+        volumes={
+            "/my-mount": modal.CloudBucketMount(
+                bucket_name="my-gcs-bucket",
+                bucket_endpoint_url="https://storage.googleapis.com",
+                secret=gcp_hmac_secret,
+            )
+        }
+    )
+    def f():
+        subprocess.run(["ls", "/my-mount"], check=True)
+    ```
+    """
+
     bucket_name: str
     bucket_endpoint_url: typing.Optional[str]
     key_prefix: typing.Optional[str]