modal.functions

modal.functions.Function

class Function(modal.object.Provider)

Functions are the basic units of serverless execution on Modal.

Generally, you will not construct a Function directly. Instead, use the @stub.function decorator on the Stub object for your application.

modal.functions.FunctionCall

class FunctionCall(modal.object.Handle)

A reference to an executed function call

Constructed using .submit(...) on a Modal function with the same arguments that a function normally takes. Acts as a reference to an ongoing function call that can be passed around and used to poll or fetch function results at some later time.

Conceptually similar to a Future/Promise/AsyncResult in other contexts and languages.

get

def get(self, timeout: Optional[float] = None):

Gets the result of the function call

Raises TimeoutError if no results are returned within timeout seconds. Setting timeout to None (the default) waits indefinitely until there is a result

get_call_graph

def get_call_graph(self) -> List[InputInfo]:

Returns a nested dictionary structure representing the call graph from a given root call ID, along with the status of execution for each node.

modal.functions.FunctionHandle

class FunctionHandle(modal.object.Handle)

Interact with a Modal Function of a live app.

web_url

@property
def web_url(self) -> str:

URL of a Function running as a web endpoint.

map

@warn_if_generator_is_not_consumed
def map(
    self,
    *input_iterators,  # one input iterator per argument in the mapped-over function/generator
    kwargs={},  # any extra keyword arguments for the function
    order_outputs=None,  # defaults to True for regular functions, False for generators
):

Parallel map over a set of inputs.

Takes one iterator argument per argument in the function being mapped over.

Example:

@stub.function
def my_func(a):
    return a ** 2

assert list(my_func.map([1, 2, 3, 4])) == [1, 4, 9, 16]

If applied to a stub.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.

If applied to a stub.generator, the results are returned as they are finished and can be out of order. By yielding zero or more than once, mapping over generators can also be used as a “flat map”.

for_each

def for_each(self, *input_iterators, **kwargs):

Execute function for all outputs, ignoring outputs

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.

starmap

@warn_if_generator_is_not_consumed
def starmap(self, input_iterator, kwargs={}, order_outputs=None):

Like map but spreads arguments over multiple function arguments

Assumes every input is a sequence (e.g. a tuple)

Example:

@stub.function
def my_func(a, b):
    return a + b

assert list(my_func.starmap([(1, 2), (3, 4)])) == [3, 7]

enqueue

def enqueue(self, *args, **kwargs):

Deprecated. Use .submit() instead when possible.

Calls the function with the given arguments, without waiting for the results.

submit

def submit(self, *args, **kwargs) -> Optional["_FunctionCall"]:

Calls the function with the given arguments, without waiting for the results.

Returns a modal.functions.FunctionCall object, that can later be polled or waited for using .get(timeout=...). Conceptually similar to multiprocessing.pool.apply_async, or a Future/Promise in other contexts.

Note: .submit() on a modal generator function does call and execute the generator, but does not currently return a function handle for polling the result.

get_raw_f

def get_raw_f(self) -> Callable:

Return the inner Python object wrapped by this Modal Function.

modal.functions.current_input_id

def current_input_id() -> str:

Returns the input id for the currently processed input

Can only be called from Modal function (i.e. in a container context)

from modal import current_input_id

@stub.function
def process_stuff():
    print(f"Starting to process {current_input_id()}")

modal.functions.exc_with_hints

def exc_with_hints(exc: BaseException):

modal.functions.gather

def gather(*function_calls: _FunctionCall):

Wait until all Modal function calls have results before returning

Accepts a variable number of FunctionCall objects as returned by Function.submit().

Returns a list of results from each function call, or raises an exception of the first failing function call.

E.g.

function_call_1 = slow_func_1.submit()
function_call_2 = slow_func_2.submit()

result_1, result_2 = gather(function_call_1, function_call_2)