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

modal/partial_function.pyi

@@ -9,6 +9,11 @@ class PartialFunction(
         modal._partial_function.P, modal._partial_function.ReturnType, modal._partial_function.OriginalReturnType
     ]
 ):
+    """Object produced by a decorator in the `modal` namespace
+
+    The object will eventually by consumed by an App decorator.
+    """
+
     raw_f: typing.Optional[collections.abc.Callable[modal._partial_function.P, modal._partial_function.ReturnType]]
     user_cls: typing.Optional[type]
     flags: modal._partial_function._PartialFunctionFlags
@@ -27,11 +32,20 @@ class PartialFunction(
         self,
         flags: modal._partial_function._PartialFunctionFlags,
         params: modal._partial_function._PartialFunctionParams,
-    ) -> typing_extensions.Self: ...
-    def validate_flag_composition(self) -> None: ...
+    ) -> typing_extensions.Self:
+        """Implement decorator composition by combining the flags and params."""
+        ...
+
+    def validate_flag_composition(self) -> None:
+        """Validate decorator composition based on PartialFunctionFlags."""
+        ...
+
     def validate_obj_compatibility(
         self, decorator_name: str, require_sync: bool = False, require_nullary: bool = False
-    ) -> None: ...
+    ) -> None:
+        """Enforce compatibility with the wrapped object; called from individual decorator functions."""
+        ...
+
     def _get_raw_f(self) -> collections.abc.Callable[modal._partial_function.P, modal._partial_function.ReturnType]: ...
     def _is_web_endpoint(self) -> bool: ...
     def __get__(
@@ -43,7 +57,22 @@ class PartialFunction(
 
 def method(
     _warn_parentheses_missing=None, *, is_generator: typing.Optional[bool] = None
-) -> modal._partial_function._MethodDecoratorType: ...
+) -> modal._partial_function._MethodDecoratorType:
+    """Decorator for methods that should be transformed into a Modal Function registered against this class's App.
+
+    **Usage:**
+
+    ```python
+    @app.cls(cpu=8)
+    class MyCls:
+
+        @modal.method()
+        def f(self):
+            ...
+    ```
+    """
+    ...
+
 def web_endpoint(
     _warn_parentheses_missing=None,
     *,
@@ -62,7 +91,25 @@ def web_endpoint(
         ]
     ],
     PartialFunction[modal._partial_function.P, modal._partial_function.ReturnType, modal._partial_function.ReturnType],
-]: ...
+]:
+    """Register a basic web endpoint with this application.
+
+    DEPRECATED: This decorator has been renamed to `@modal.fastapi_endpoint`.
+
+    This is the simple way to create a web endpoint on Modal. The function
+    behaves as a [FastAPI](https://fastapi.tiangolo.com/) handler and should
+    return a response object to the caller.
+
+    Endpoints created with `@modal.web_endpoint` are meant to be simple, single
+    request handlers and automatically have
+    [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) enabled.
+    For more flexibility, use `@modal.asgi_app`.
+
+    To learn how to use Modal with popular web frameworks, see the
+    [guide on web endpoints](https://modal.com/docs/guide/webhooks).
+    """
+    ...
+
 def fastapi_endpoint(
     _warn_parentheses_missing=None,
     *,
@@ -81,7 +128,24 @@ def fastapi_endpoint(
         ]
     ],
     PartialFunction[modal._partial_function.P, modal._partial_function.ReturnType, modal._partial_function.ReturnType],
-]: ...
+]:
+    """Convert a function into a basic web endpoint by wrapping it with a FastAPI App.
+
+    Modal will internally use [FastAPI](https://fastapi.tiangolo.com/) to expose a
+    simple, single request handler. If you are defining your own `FastAPI` application
+    (e.g. if you want to define multiple routes), use `@modal.asgi_app` instead.
+
+    The endpoint created with this decorator will automatically have
+    [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) enabled
+    and can leverage many of FastAPI's features.
+
+    For more information on using Modal with popular web frameworks, see our
+    [guide on web endpoints](https://modal.com/docs/guide/webhooks).
+
+    *Added in v0.73.82*: This function replaces the deprecated `@web_endpoint` decorator.
+    """
+    ...
+
 def asgi_app(
     _warn_parentheses_missing=None,
     *,
@@ -97,7 +161,30 @@ def asgi_app(
         ]
     ],
     PartialFunction,
-]: ...
+]:
+    """Decorator for registering an ASGI app with a Modal function.
+
+    Asynchronous Server Gateway Interface (ASGI) is a standard for Python
+    synchronous and asynchronous apps, supported by all popular Python web
+    libraries. This is an advanced decorator that gives full flexibility in
+    defining one or more web endpoints on Modal.
+
+    **Usage:**
+
+    ```python
+    from typing import Callable
+
+    @app.function()
+    @modal.asgi_app()
+    def create_asgi() -> Callable:
+        ...
+    ```
+
+    To learn how to use Modal with popular web frameworks, see the
+    [guide on web endpoints](https://modal.com/docs/guide/webhooks).
+    """
+    ...
+
 def wsgi_app(
     _warn_parentheses_missing=None,
     *,
@@ -113,7 +200,30 @@ def wsgi_app(
         ]
     ],
     PartialFunction,
-]: ...
+]:
+    """Decorator for registering a WSGI app with a Modal function.
+
+    Web Server Gateway Interface (WSGI) is a standard for synchronous Python web apps.
+    It has been [succeeded by the ASGI interface](https://asgi.readthedocs.io/en/latest/introduction.html#wsgi-compatibility)
+    which is compatible with ASGI and supports additional functionality such as web sockets.
+    Modal supports ASGI via [`asgi_app`](https://modal.com/docs/reference/modal.asgi_app).
+
+    **Usage:**
+
+    ```python
+    from typing import Callable
+
+    @app.function()
+    @modal.wsgi_app()
+    def create_wsgi() -> Callable:
+        ...
+    ```
+
+    To learn how to use this decorator with popular web frameworks, see the
+    [guide on web endpoints](https://modal.com/docs/guide/webhooks).
+    """
+    ...
+
 def web_server(
     port: int,
     *,
@@ -130,20 +240,84 @@ def web_server(
         ]
     ],
     PartialFunction,
-]: ...
+]:
+    """Decorator that registers an HTTP web server inside the container.
+
+    This is similar to `@asgi_app` and `@wsgi_app`, but it allows you to expose a full HTTP server
+    listening on a container port. This is useful for servers written in other languages like Rust,
+    as well as integrating with non-ASGI frameworks like aiohttp and Tornado.
+
+    **Usage:**
+
+    ```python
+    import subprocess
+
+    @app.function()
+    @modal.web_server(8000)
+    def my_file_server():
+        subprocess.Popen("python -m http.server -d / 8000", shell=True)
+    ```
+
+    The above example starts a simple file server, displaying the contents of the root directory.
+    Here, requests to the web endpoint will go to external port 8000 on the container. The
+    `http.server` module is included with Python, but you could run anything here.
+
+    Internally, the web server is transparently converted into a web endpoint by Modal, so it has
+    the same serverless autoscaling behavior as other web endpoints.
+
+    For more info, see the [guide on web endpoints](https://modal.com/docs/guide/webhooks).
+    """
+    ...
+
 def build(
     _warn_parentheses_missing=None, *, force: bool = False, timeout: int = 86400
 ) -> collections.abc.Callable[
     [typing.Union[PartialFunction, collections.abc.Callable[[typing.Any], typing.Any]]], PartialFunction
-]: ...
+]:
+    """mdmd:hidden
+    Decorator for methods that execute at _build time_ to create a new Image layer.
+
+    **Deprecated**: This function is deprecated. We recommend using `modal.Volume`
+    to store large assets (such as model weights) instead of writing them to the
+    Image during the build process. For other use cases, you can replace this
+    decorator with the `Image.run_function` method.
+
+    **Usage**
+
+    ```python notest
+    @app.cls(gpu="A10G")
+    class AlpacaLoRAModel:
+        @build()
+        def download_models(self):
+            model = LlamaForCausalLM.from_pretrained(
+                base_model,
+            )
+            PeftModel.from_pretrained(model, lora_weights)
+            LlamaTokenizer.from_pretrained(base_model)
+    ```
+    """
+    ...
+
 def enter(
     _warn_parentheses_missing=None, *, snap: bool = False
 ) -> collections.abc.Callable[
     [typing.Union[PartialFunction, collections.abc.Callable[[typing.Any], typing.Any]]], PartialFunction
-]: ...
+]:
+    """Decorator for methods which should be executed when a new container is started.
+
+    See the [lifeycle function guide](https://modal.com/docs/guide/lifecycle-functions#enter) for more information.
+    """
+    ...
+
 def exit(
     _warn_parentheses_missing=None,
-) -> collections.abc.Callable[[collections.abc.Callable[[typing.Any], typing.Any]], PartialFunction]: ...
+) -> collections.abc.Callable[[collections.abc.Callable[[typing.Any], typing.Any]], PartialFunction]:
+    """Decorator for methods which should be executed when a container is about to exit.
+
+    See the [lifeycle function guide](https://modal.com/docs/guide/lifecycle-functions#exit) for more information.
+    """
+    ...
+
 def batched(
     _warn_parentheses_missing=None, *, max_batch_size: int, wait_ms: int
 ) -> collections.abc.Callable[
@@ -156,7 +330,33 @@ def batched(
         ]
     ],
     PartialFunction[modal._partial_function.P, modal._partial_function.ReturnType, modal._partial_function.ReturnType],
-]: ...
+]:
+    """Decorator for functions or class methods that should be batched.
+
+    **Usage**
+
+    ```python
+    # Stack the decorator under `@app.function()` to enable dynamic batching
+    @app.function()
+    @modal.batched(max_batch_size=4, wait_ms=1000)
+    async def batched_multiply(xs: list[int], ys: list[int]) -> list[int]:
+        return [x * y for x, y in zip(xs, ys)]
+
+    # call batched_multiply with individual inputs
+    # batched_multiply.remote.aio(2, 100)
+
+    # With `@app.cls()`, apply the decorator to a method (this may change in the future)
+    @app.cls()
+    class BatchedClass:
+        @modal.batched(max_batch_size=4, wait_ms=1000)
+        def batched_multiply(self, xs: list[int], ys: list[int]) -> list[int]:
+            return [x * y for x, y in zip(xs, ys)]
+    ```
+
+    See the [dynamic batching guide](https://modal.com/docs/guide/dynamic-batching) for more information.
+    """
+    ...
+
 def concurrent(
     _warn_parentheses_missing=None, *, max_inputs: int, target_inputs: typing.Optional[int] = None
 ) -> collections.abc.Callable[
@@ -169,4 +369,45 @@ def concurrent(
         ]
     ],
     PartialFunction[modal._partial_function.P, modal._partial_function.ReturnType, modal._partial_function.ReturnType],
-]: ...
+]:
+    """Decorator that allows individual containers to handle multiple inputs concurrently.
+
+    The concurrency mechanism depends on whether the function is async or not:
+    - Async functions will run inputs on a single thread as asyncio tasks.
+    - Synchronous functions will use multi-threading. The code must be thread-safe.
+
+    Input concurrency will be most useful for workflows that are IO-bound
+    (e.g., making network requests) or when running an inference server that supports
+    dynamic batching.
+
+    When `target_inputs` is set, Modal's autoscaler will try to provision resources
+    such that each container is running that many inputs concurrently, rather than
+    autoscaling based on `max_inputs`. Containers may burst up to up to `max_inputs`
+    if resources are insufficient to remain at the target concurrency, e.g. when the
+    arrival rate of inputs increases. This can trade-off a small increase in average
+    latency to avoid larger tail latencies from input queuing.
+
+    **Examples:**
+    ```python
+    # Stack the decorator under `@app.function()` to enable input concurrency
+    @app.function()
+    @modal.concurrent(max_inputs=100)
+    async def f(data):
+        # Async function; will be scheduled as asyncio task
+        ...
+
+    # With `@app.cls()`, apply the decorator at the class level, not on individual methods
+    @app.cls()
+    @modal.concurrent(max_inputs=100, target_inputs=80)
+    class C:
+        @modal.method()
+        def f(self, data):
+            # Sync function; must be thread-safe
+            ...
+
+    ```
+
+    *Added in v0.73.148:* This decorator replaces the `allow_concurrent_inputs` parameter
+    in `@app.function()` and `@app.cls()`.
+    """
+    ...

modal/proxy.py

@@ -12,7 +12,7 @@ class _Proxy(_Object, type_prefix="pr"):
     """Proxy objects give your Modal containers a static outbound IP address.
 
     This can be used for connecting to a remote address with network whitelist, for example
-    a database. See [the guide](/docs/guide/proxy-ips) for more information.
+    a database. See [the guide](https://modal.com/docs/guide/proxy-ips) for more information.
     """
 
     @staticmethod

modal/proxy.pyi

@@ -3,10 +3,35 @@ import modal.object
 import typing
 
 class _Proxy(modal._object._Object):
+    """Proxy objects give your Modal containers a static outbound IP address.
+
+    This can be used for connecting to a remote address with network whitelist, for example
+    a database. See [the guide](https://modal.com/docs/guide/proxy-ips) for more information.
+    """
     @staticmethod
-    def from_name(name: str, *, environment_name: typing.Optional[str] = None) -> _Proxy: ...
+    def from_name(name: str, *, environment_name: typing.Optional[str] = None) -> _Proxy:
+        """Reference a Proxy by its name.
+
+        In contrast to most other Modal objects, new Proxy objects must be
+        provisioned via the Dashboard and cannot be created on the fly from code.
+        """
+        ...
 
 class Proxy(modal.object.Object):
-    def __init__(self, *args, **kwargs): ...
+    """Proxy objects give your Modal containers a static outbound IP address.
+
+    This can be used for connecting to a remote address with network whitelist, for example
+    a database. See [the guide](https://modal.com/docs/guide/proxy-ips) for more information.
+    """
+    def __init__(self, *args, **kwargs):
+        """mdmd:hidden"""
+        ...
+
     @staticmethod
-    def from_name(name: str, *, environment_name: typing.Optional[str] = None) -> Proxy: ...
+    def from_name(name: str, *, environment_name: typing.Optional[str] = None) -> Proxy:
+        """Reference a Proxy by its name.
+
+        In contrast to most other Modal objects, new Proxy objects must be
+        provisioned via the Dashboard and cannot be created on the fly from code.
+        """
+        ...

modal/queue.py

@@ -64,7 +64,7 @@ class _Queue(_Object, type_prefix="qu"):
     assert queue.get() == 42
     ```
 
-    For more examples, see the [guide](/docs/guide/dicts-and-queues#modal-queues).
+    For more examples, see the [guide](https://modal.com/docs/guide/dicts-and-queues#modal-queues).
 
     **Queue partitions (beta)**
 
@@ -154,9 +154,9 @@ class _Queue(_Object, type_prefix="qu"):
     ) -> "_Queue":
         """Reference a named Queue, creating if necessary.
 
-        In contrast to `modal.Queue.lookup`, this is a lazy method
-        the defers hydrating the local object with metadata from
-        Modal servers until the first time it is actually used.
+        This is a lazy method the defers hydrating the local
+        object with metadata from Modal servers until the first
+        time it is actually used.
 
         ```python
         q = modal.Queue.from_name("my-queue", create_if_missing=True)