Function#

A Function is a portable code block that can be sent to remote hardware to run as a subroutine or service. It is comprised of the entrypoint, system (Cluster), and requirements necessary to run it.

Function Factory Methods#

runhouse.function(fn: str | Callable | None = None, name: str | None = None, system: str | Cluster | None = None, env: str | List[str] | Env | None = None, dryrun: bool = False, load_secrets: bool = False, serialize_notebook_fn: bool = False)[source]#

Builds an instance of Function.

Parameters:

  • fn (Optional[str or Callable]) – The function to execute on the remote system when the function is called.

  • name (Optional[str]) – Name of the Function to create or retrieve. This can be either from a local config or from the RNS.

  • env (Optional[List[str] or Env or str]) – List of requirements to install on the remote cluster, or path to the requirements.txt file, or Env object or string name of an Env object.

  • dryrun (bool) – Whether to create the Function if it doesn’t exist, or load the Function object as a dryrun. (Default: False)

  • load_secrets (bool) – Whether or not to send secrets; only applicable if dryrun is set to False. (Default: False)

  • serialize_notebook_fn (bool) – If function is of a notebook setting, whether or not to serialized the function. (Default: False)

Returns:

The resulting Function object.

Return type:

Function

Example

>>> import runhouse as rh

>>> cluster = rh.ondemand_cluster(name="my_cluster")
>>> def sum(a, b):
>>>    return a + b

>>> summer = rh.function(fn=sum, name="my_func").to(cluster, env=['requirements.txt']).save()

>>> # using the function
>>> res = summer(5, 8)  # returns 13

>>> # Load function from above
>>> reloaded_function = rh.function(name="my_func")
runhouse.aws_lambda_fn(fn: Callable | None = None, name: str | None = None, env: Dict | List[str] | Env | None = None, runtime: str | None = None, timeout: int | None = None, memory_size: int | None = None, tmp_size: int | None = None, retention_time: int | None = None, dryrun: bool = False)[source]#

Builds an instance of LambdaFunction.

Parameters:

  • fn (Optional[Callable]) – The Lambda function to be executed.

  • name (Optional[str]) – Name of the Lambda Function to create or retrieve. This can be either from a local config or from the RNS.

  • env (Optional[Dict or List[str] or Env]) –

    Specifies the requirements that will be installed, and the environment vars that should be attached to the Lambda. Accepts three possible types:

    1. A dict which should contain the following keys:

      a. reqs: a list of the python libraries, to be installed by the Lambda, or just a requirements.txt string.

      1. env_vars: dictionary containing the env_vars that will be a part of the lambda configuration.

    2. A list of strings, containing all the required python packages.

    3. An instance of Runhouse Env class.

    By default, runhouse package will be installed, and env_vars will include {HOME: /tmp/home}.

  • runtime – (Optional[str]): The coding language of the function. Should be one of the following: python3.7, python3.8, python3.9, python3.10, python3.11. (Default: python3.9)

  • timeout – Optional[int]: The maximum amount of time (in seconds) during which the Lambda will run in AWS without timing-out. (Default: 900, Min: 3, Max: 900)

  • memory_size – Optional[int], The amount of memory (in MB) to be allocated to the Lambda. (Default: 10240, Min: 128, Max: 10240)

  • tmp_size – Optional[int], This size of the /tmp folder in the aws lambda file system. (Default: 10240, Min: 512, Max: 10240).

  • retention_time – Optional[int] The time (in days) the Lambda execution logs will be saved in AWS cloudwatch. After that, they will be deleted. (Default: 30 days)

  • dryrun (bool) – Whether to create the Function if it doesn’t exist, or load the Function object as a dryrun. (Default: False).

Returns:

The resulting AWS Lambda Function object.

Note

When creating a Lambda function for the first time (not reloading it), a callable function is a mandatory argument.

Return type:

LambdaFunction

Examples

>>> import runhouse as rh

>>> # Pass in a callable function  when creating a Lambda
>>> def multiply(a, b):
>>>     return a * b
>>> multiply_lambda = rh.aws_lambda_fn(fn=multiply, name="lambdas_mult_func")
>>> mult_res = multiply_lambda(4, 5)  # returns 20.

>>> # Load function from above
>>> reloaded_function = rh.aws_lambda_fn(name="lambdas_mult_func")
>>> reloaded_function_res = reloaded_function(3, 4)  # returns 12.

Function Class#

class runhouse.Function(fn_pointers: Tuple | None = None, name: str | None = None, system: Cluster | None = None, env: Env | None = None, dryrun: bool = False, **kwargs)[source]#
__init__(fn_pointers: Tuple | None = None, name: str | None = None, system: Cluster | None = None, env: Env | None = None, dryrun: bool = False, **kwargs)[source]#

Runhouse Function object. It is comprised of the entrypoint, system/cluster, and dependencies necessary to run the service.

Note

To create a Function, please use the factory method function().

classmethod from_config(config: dict, dryrun: bool = False)[source]#

Create a Function object from a config dictionary.

get(run_key)[source]#

Get the result of a Function call that was submitted as async using run.

Parameters:

run_key – A single or list of runhouse run_key strings returned by calling .call.remote() on the Function. The ObjectRefs must be from the cluster that this Function is running on.

Example

>>> remote_fn = rh.function(local_fn).to(gpu)
>>> remote_fn_run = remote_fn.run()
>>> remote_fn.get(remote_fn_run.name)
http_url(curl_command=False, *args, **kwargs) → str[source]#

Return the endpoint needed to run the Function on the remote cluster, or provide the curl command if requested.

keep_warm(autostop_mins=None)[source]#

Keep the system warm for autostop_mins. If autostop_mins is None or -1, keep warm indefinitely.

Example

>>> # keep gpu warm for 30 mins
>>> remote_fn = rh.function(local_fn).to(gpu)
>>> remote_fn.keep_warm(autostop_mins=30)
method_signature(method)[source]#

Extracts the properties of a method that we want to preserve when sending the method over the wire.

notebook(persist=False, sync_package_on_close=None, port_forward=8888)[source]#

Tunnel into and launch notebook from the system.

share(*args, visibility=None, **kwargs)[source]#

Grant access to the resource for a list of users (or a single user). If a user has a Runhouse account they will receive an email notifying them of their new access. If the user does not have a Runhouse account they will also receive instructions on creating one, after which they will be able to have access to the Resource. If visibility is set to public, users will not be notified.

Note

You can only grant access to other users if you have write access to the resource.

Parameters:

  • users (Union[str, list], optional) – Single user or list of user emails and / or runhouse account usernames. If none are provided and visibility is set to public, resource will be made publicly available to all users.

  • access_level (ResourceAccess, optional) – Access level to provide for the resource. Defaults to read.

  • visibility (ResourceVisibility, optional) – Type of visibility to provide for the shared resource. Defaults to private.

  • notify_users (bool, optional) – Whether to send an email notification to users who have been given access. Note: This is relevant for resources which are not shareable. Defaults to True.

  • headers (dict, optional) – Request headers to provide for the request to RNS. Contains the user’s auth token. Example: {"Authorization": f"Bearer {token}"}

Returns:

added_users:

Users who already have a Runhouse account and have been granted access to the resource.

new_users:

Users who do not have Runhouse accounts and received notifications via their emails.

valid_users:

Set of valid usernames and emails from users parameter.

Return type:

Tuple(Dict, Dict, Set)

Example

>>> # Write access to the resource for these specific users.
>>> # Visibility will be set to private (users can search for and view resource in Den dashboard)
>>> my_resource.share(users=["username1", "[email protected]"], access_level='write')

>>> # Make resource public, with read access to the resource for all users
>>> my_resource.share(visibility='public')
to(system: str | Cluster | None = None, env: List[str] | Env = [], force_install: bool = False)[source]#

Set up a Function and Env on the given system. If the function is sent to AWS, the system should be aws_lambda See the args of the factory method function() for more information.

Example

>>> rh.function(fn=local_fn).to(gpu_cluster)
>>> rh.function(fn=local_fn).to(system=gpu_cluster, env=my_conda_env)
>>> rh.function(fn=local_fn).to(system='aws_lambda')  # will deploy the rh.function to AWS as a Lambda.

Lambda Function Class#

Note

Lambda Function support is an alpha and under active development. Please report any bugs and let us know of any feature requests.

A Lambda Function is a serverless compute service provided by AWS. It allows you to run applications and backend services without provisioning or managing servers. Runhouse will allow you to maintain, invoke and share your Lambda functions and their code. It is comprised of the entry point, configuration, and dependencies necessary to run the service.
There are few core options to create an AWS Lambda using Runhouse:

  1. Pass a callable Python function to the factory method.

  2. Follow a typical Lambda creation flow (as if you are using AWS APIs). That includes passing path(s) to Python files(s) (containing the code) and a handler function name to the from_handler_file() method. Arguments such as runtime, Lambda name, timeout and memory size are accepted by the from_handler_file() method as well, but they are not mandatory and have default values.

  3. Create rh.function instance, and than send it over to AWS Lambdas. For example: rh.function(summer).to(system="aws_lambda")

class runhouse.LambdaFunction(paths_to_code: List[str], handler_function_name: str, runtime: str, fn_pointers: tuple, name: str, env: Env, timeout: int, memory_size: int, tmp_size: int, retention_time: int = 30, dryrun: bool = False, access: str | None = None, **kwargs)[source]#
__init__(paths_to_code: List[str], handler_function_name: str, runtime: str, fn_pointers: tuple, name: str, env: Env, timeout: int, memory_size: int, tmp_size: int, retention_time: int = 30, dryrun: bool = False, access: str | None = None, **kwargs)[source]#

Runhouse AWS Lambda object. It is comprised of the entry point, configuration, and dependencies necessary to run the service on AWS infra.

Note

To create an AWS lambda resource, please use the factory method aws_lambda_fn().

classmethod from_config(config: dict, dryrun: bool = False)[source]#

Create an AWS Lambda object from a config dictionary.

classmethod from_handler_file(paths_to_code: List[str], handler_function_name: str, name: str | None = None, env: dict | None = None, runtime: str | None = None, timeout: int | None = None, memory_size: int | None = None, tmp_size: int | None = None, retention_time: int | None = None, dryrun: bool = False)[source]#

Creates an AWS Lambda function from a Python file.

Parameters:

  • paths_to_code – (Optional[List[str]]): List of the FULL paths to the Python code file(s) that should be sent to AWS Lambda. First path in the list should be the path to the handler file which contains the main (handler) function. If fn is provided, this argument is ignored.

  • handler_function_name – (Optional[str]): The name of the function in the handler file that will be executed by the Lambda. If fn is provided, this argument is ignored.

  • runtime – (Optional[str]): The coding language of the function. Should be one of the following: python3.7, python3.8, python3.9, python3.10, python3.11. (Default: python3.9)

  • name (Optional[str]) – Name of the Lambda Function to create or retrieve. This can be either from a local config or from the RNS.

  • env (Optional[Dict or List[str] or Env]) –

    Specifies the requirements that will be installed, and the environment vars that should be attached to the Lambda. Accepts three possible types:

    1. A dict which should contain the following keys:

      reqs: a list of the python libraries, to be installed by the Lambda, or just a ``requirements.txt``string.

      env_vars: dictionary containing the env_vars that will be a part of the lambda configuration.

    2. A list of strings, containing all the required python packages.

    3. An instance of Runhouse Env class. By default, runhouse package will be installed, and env_vars will include {HOME: /tmp/home}.

  • timeout – Optional[int]: The maximum amount of time (in seconds) during which the Lambda will run in AWS without timing-out. (Default: 900, Min: 3, Max: 900)

  • memory_size – Optional[int], The amount of memory (in MB) to be allocated to the Lambda. (Default: 10240, Min: 128, Max: 10240)

  • tmp_size – Optional[int], This size of the /tmp folder in the aws lambda file system. (Default: 10240, Min: 512, Max: 10240).

  • retention_time – Optional[int] The time (in days) the Lambda execution logs will be saved in AWS cloudwatch. After that, they will be deleted. (Default: 30 days)

  • dryrun (bool) – Whether to create the Function if it doesn’t exist, or load the Function object as a dryrun. (Default: False).

Returns:

The resulting AWS Lambda Function object.

Return type:

LambdaFunction

Example

>>> # handler_file.py
>>> def summer(a, b):
>>>    return a + b

>>> # your 'main' python file, where you are using runhouse
>>> summer_lambda = rh.LambdaFunction.from_handler_file(
>>>                     paths_to_code=['/full/path/to/handler_file.py'],
>>>                     handler_function_name = 'summer',
>>>                     runtime = 'python3.9',
>>>                     name="my_func").save()

>>> # invoking the function
>>> summer_res = summer_lambda(5, 8)  # returns 13.
classmethod from_name(name, dryrun=False, alt_options=None)[source]#

Load existing Resource via its name.

map(*args, **kwargs)[source]#

Map a function over a list of arguments.

Example

>>> # The my_lambda_handler.py file
>>> def my_summer(arg1, arg2, arg3):
>>>     return arg1 + arg2 + arg3
>>>
>>> # your 'main' python file, where you are using runhouse
>>> summer_lambda = rh.aws_lambda_fn(
>>>                     fn=my_summer,
>>>                     runtime = 'python3.9',
>>>                     name="my_func")
>>> output = summer_lambda.map([1, 2], [1, 4], [2, 3])  # output = [4, 9]
starmap(args_lists, **kwargs)[source]#

Like map() except that the elements of the iterable are expected to be iterables that are unpacked as arguments. An iterable of [(1,2), (3, 4)] results in [func(1,2), func(3,4)].

Example

>>> arg_list = [(1,2, 3), (3, 4, 5)]
>>> # invokes the Lambda function twice, once with args (1, 2, 3) and once with args (3, 4, 5)
>>> output = summer_lambda.starmap(arg_list) # output = [6, 12]
teardown()[source]#

Deletes a Lambda function instance from AWS. All relevant AWS resources (role, log group) are deleted as well.

Example

>>> def multiply(a, b):
>>>     return a * b
>>> multiply_lambda = rh.aws_lambda_fn(fn=multiply, name="lambdas_mult_func")
>>> mult_res = multiply_lambda(4, 5)  # returns 20.
>>> multiply_lambda.teardown()  # returns true if succeeded, raises an exception otherwise.

Lambda Hardware Setup#

To create an AWS Lambda, you must grant the necessary permissions to do so. They are provided by an IAM role, which should be attached to a certain AWS profile. This setup is made in the ~/.aws/config file.

For example, your local ~/.aws/config contains:

[profile lambda]
role_arn = arn:aws:iam::123456789:role/lambda-creation-role
region = us-east-1
source_profile = default

There are several ways to provide the necessary credentials which enables Lambda creation:

  1. Specify the profile name in your code editor:

    1. Install the AWS Toolkit extension.

    2. Choose the relevant profile (e.g. profile lambda) and region (e.g us-east-1).

  2. Environment Variable: setting AWS_PROFILE to "lambda"

Note

If no specific profile is provided, Runhouse will try using the default profile. Note if this default AWS identity will not have the relevant IAM permissions for creating a Lambda, you will not be able to create a Lambda.