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

modal/parallel_map.pyi

@@ -12,6 +12,7 @@ import typing
 import typing_extensions
 
 class _SynchronizedQueue:
+    """mdmd:hidden"""
     async def init(self): ...
     async def put(self, item): ...
     async def get(self): ...
@@ -19,7 +20,10 @@ class _SynchronizedQueue:
 SUPERSELF = typing.TypeVar("SUPERSELF", covariant=True)
 
 class SynchronizedQueue:
-    def __init__(self, /, *args, **kwargs): ...
+    """mdmd:hidden"""
+    def __init__(self, /, *args, **kwargs):
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
 
     class __init_spec(typing_extensions.Protocol[SUPERSELF]):
         def __call__(self, /): ...
@@ -40,11 +44,21 @@ class SynchronizedQueue:
     get: __get_spec[typing_extensions.Self]
 
 class _OutputValue:
+    """_OutputValue(value: Any)"""
+
     value: typing.Any
 
-    def __init__(self, value: typing.Any) -> None: ...
-    def __repr__(self): ...
-    def __eq__(self, other): ...
+    def __init__(self, value: typing.Any) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    def __repr__(self):
+        """Return repr(self)."""
+        ...
+
+    def __eq__(self, other):
+        """Return self==value."""
+        ...
 
 def _map_invocation(
     function: modal._functions._Function,
@@ -63,7 +77,20 @@ def _map_helper(
     order_outputs: bool = True,
     return_exceptions: bool = False,
     wrap_returned_exceptions: bool = True,
-) -> typing.AsyncGenerator[typing.Any, None]: ...
+) -> typing.AsyncGenerator[typing.Any, None]:
+    """Core implementation that supports `_map_async()`, `_starmap_async()` and `_for_each_async()`.
+
+    Runs in an event loop on the main thread. Concurrently feeds new input to the input queue and yields available
+    outputs to the caller.
+
+    Note that since the iterator(s) can block, it's a bit opaque how often the event
+    loop decides to get a new input vs how often it will emit a new output.
+
+    We could make this explicit as an improvement or even let users decide what they
+    prefer: throughput (prioritize queueing inputs) or latency (prioritize yielding results)
+    """
+    ...
+
 def _map_async(
     self: modal.functions.Function,
     *input_iterators: typing.Union[typing.Iterable[typing.Any], typing.AsyncIterable[typing.Any]],
@@ -91,10 +118,81 @@ def _map_sync(
     order_outputs: bool = True,
     return_exceptions: bool = False,
     wrap_returned_exceptions: bool = True,
-) -> modal._utils.async_utils.AsyncOrSyncIterable: ...
-async def _spawn_map_async(self, *input_iterators, kwargs={}) -> None: ...
-def _spawn_map_sync(self, *input_iterators, kwargs={}) -> None: ...
-def _for_each_sync(self, *input_iterators, kwargs={}, ignore_exceptions: bool = False): ...
+) -> modal._utils.async_utils.AsyncOrSyncIterable:
+    """Parallel map over a set of inputs.
+
+    Takes one iterator argument per argument in the function being mapped over.
+
+    Example:
+    ```python
+    @app.function()
+    def my_func(a):
+        return a ** 2
+
+
+    @app.local_entrypoint()
+    def main():
+        assert list(my_func.map([1, 2, 3, 4])) == [1, 4, 9, 16]
+    ```
+
+    If applied to a `app.function`, `map()` returns one result per input and the output order
+    is guaranteed to be the same as the input order. Set `order_outputs=False` to return results
+    in the order that they are completed instead.
+
+    `return_exceptions` can be used to treat exceptions as successful results:
+
+    ```python
+    @app.function()
+    def my_func(a):
+        if a == 2:
+            raise Exception("ohno")
+        return a ** 2
+
+
+    @app.local_entrypoint()
+    def main():
+        # [0, 1, UserCodeException(Exception('ohno'))]
+        print(list(my_func.map(range(3), return_exceptions=True)))
+    ```
+    """
+    ...
+
+async def _spawn_map_async(self, *input_iterators, kwargs={}) -> None:
+    """This runs in an event loop on the main thread. It consumes inputs from the input iterators and creates async
+    function calls for each.
+    """
+    ...
+
+def _spawn_map_sync(self, *input_iterators, kwargs={}) -> None:
+    """Spawn parallel execution over a set of inputs, exiting as soon as the inputs are created (without waiting
+    for the map to complete).
+
+    Takes one iterator argument per argument in the function being mapped over.
+
+    Example:
+    ```python
+    @app.function()
+    def my_func(a):
+        return a ** 2
+
+
+    @app.local_entrypoint()
+    def main():
+        my_func.spawn_map([1, 2, 3, 4])
+    ```
+
+    Programmatic retrieval of results will be supported in a future update.
+    """
+    ...
+
+def _for_each_sync(self, *input_iterators, kwargs={}, ignore_exceptions: bool = False):
+    """Execute function for all inputs, ignoring outputs. Waits for completion of the inputs.
+
+    Convenient alias for `.map()` in cases where the function just needs to be called.
+    as the caller doesn't have to consume the generator to process the inputs.
+    """
+    ...
+
 def _starmap_sync(
     self,
     input_iterator: typing.Iterable[typing.Sequence[typing.Any]],
@@ -103,7 +201,24 @@ def _starmap_sync(
     order_outputs: bool = True,
     return_exceptions: bool = False,
     wrap_returned_exceptions: bool = True,
-) -> modal._utils.async_utils.AsyncOrSyncIterable: ...
+) -> modal._utils.async_utils.AsyncOrSyncIterable:
+    """Like `map`, but spreads arguments over multiple function arguments.
+
+    Assumes every input is a sequence (e.g. a tuple).
+
+    Example:
+    ```python
+    @app.function()
+    def my_func(a, b):
+        return a + b
+
+
+    @app.local_entrypoint()
+    def main():
+        assert list(my_func.starmap([(1, 2), (3, 4)])) == [3, 7]
+    ```
+    """
+    ...
 
 class _MapItemState(enum.Enum):
     # The input is being sent the server with a PutInputs request, but the response has not been received yet.
@@ -140,7 +255,10 @@ class _MapItemContext:
         input: modal_proto.api_pb2.FunctionInput,
         retry_manager: modal.retries.RetryManager,
         sync_client_retries_enabled: bool,
-    ): ...
+    ):
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
     def handle_put_inputs_response(self, item: modal_proto.api_pb2.FunctionPutInputsResponseItem): ...
     async def handle_get_outputs_response(
         self,
@@ -148,7 +266,13 @@ class _MapItemContext:
         now_seconds: int,
         function_call_invocation_type: int,
         retry_queue: modal._utils.async_utils.TimestampPriorityQueue,
-    ) -> _OutputType: ...
+    ) -> _OutputType:
+        """Processes the output, and determines if it is complete or needs to be retried.
+
+        Return True if input state was changed to COMPLETE, otherwise False.
+        """
+        ...
+
     async def prepare_item_for_retry(self) -> modal_proto.api_pb2.FunctionRetryInputsItem: ...
     def handle_retry_response(self, input_jwt: str): ...
 
@@ -160,12 +284,18 @@ class _MapItemsManager:
         retry_queue: modal._utils.async_utils.TimestampPriorityQueue,
         sync_client_retries_enabled: bool,
         max_inputs_outstanding: int,
-    ): ...
+    ):
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
     async def add_items(self, items: list[modal_proto.api_pb2.FunctionPutInputsItem]): ...
     async def prepare_items_for_retry(
         self, retriable_idxs: list[int]
     ) -> list[modal_proto.api_pb2.FunctionRetryInputsItem]: ...
-    def get_input_jwts_waiting_for_output(self) -> list[str]: ...
+    def get_input_jwts_waiting_for_output(self) -> list[str]:
+        """Returns a list of input_jwts for inputs that are waiting for output."""
+        ...
+
     def _remove_item(self, item_idx: int): ...
     def get_item_context(self, item_idx: int) -> _MapItemContext: ...
     def handle_put_inputs_response(self, items: list[modal_proto.api_pb2.FunctionPutInputsResponseItem]): ...

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)**