Getting Started
API Basics
API Reference
Other Topics
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.
Builds an instance of Function.
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. (Default: None)
env (Optional[List[str] or Env or str], optional) – 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. (Default: None)
load_from_den (bool, optional) – Whether to try loading the function from Den. (Default: True)
dryrun (bool, optional) – Whether to create the Function if it doesn’t exist, or load the Function object as
a dryrun. (Default: False)
serialize_notebook_fn (bool, optional) – If function is of a notebook setting, whether or not to serialized the
function. (Default: False)
The resulting Function object.
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")
Builds an instance of LambdaFunction.
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:
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.
env_vars: dictionary containing the env_vars that will be a part of the lambda configuration.
A list of strings, containing all the required python packages.
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)
load_from_den (bool) – Whether to try loading the Function resource from Den. (Default: True)
dryrun (bool) – Whether to create the Function if it doesn’t exist, or load the Function object as a dryrun.
(Default: False).
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.
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.
- __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().
The config of the function.
condensed (bool, optional) – Whether to return the condensed config without expanding children subresources,
or return the whole expanded config. (Default: True)
Load or construct resource from config.
config (Dict) – Resource config.
dryrun (bool, optional) – Whether to construct resource or load as dryrun (Default: False)
Get the result of a Function call that was submitted as async using run.
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)
Method signature, consisting of method properties to preserve when sending the method over the wire.
Grant access to the resource for a list of users (or a single user). By default, the user will
receive an email notification of access (if they have a Runhouse account) or instructions on creating
an account to access 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.
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. (Default: None)
access_level (ResourceAccess, optional) – Access level to provide for the resource.
(Default: read).
visibility (ResourceVisibility, optional) – Type of visibility to provide for the shared
resource. By default, the visibility is private. (Default: None)
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. (Default: True)
headers (Dict, optional) – Request headers to provide for the request to RNS. Contains the user’s auth token.
Example: {"Authorization": f"Bearer {token}"}
Users who already have a Runhouse account and have been granted access to the resource.
Users who do not have Runhouse accounts and received notifications via their emails.
Set of valid usernames and emails from users parameter.
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", "user2@gmail.com"], access_level='write')
>>> # Make resource public, with read access to the resource for all users >>> my_resource.share(visibility='public')
Send the function to the specified env on the cluster. This will sync over relevant code and packages onto the cluster, and set up the environment if it does not yet exist on the cluster.
system (str or Cluster) – The system to setup the function and env on.
env (str, List[str], or Env, optional) – The environment where the function lives on in the cluster,
or the set of requirements necessary to run the function. (Default: None)
name (Optional[str], optional) – Name to give to the function resource, if you wish to rename it.
(Default: None)
force_install (bool, optional) – Whether to re-install and perform the environment setup steps, even
if it may already exist on the cluster. (Defualt: False)
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.
Note
Lambda Function support is an alpha and under active development. Please report any bugs and let us know of any feature requests.
Pass a callable Python function to the factory method.
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.
Create rh.function instance, and than send it over to AWS Lambdas. For example:
rh.function(summer).to(system="aws_lambda")
- __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().
The config of the function.
condensed (bool, optional) – Whether to return the condensed config without expanding children subresources,
or return the whole expanded config. (Default: True)
Load or construct resource from config.
config (Dict) – Resource config.
dryrun (bool, optional) – Whether to construct resource or load as dryrun (Default: False)
Creates an AWS Lambda function from a Python file.
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:
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.
A list of strings, containing all the required python packages.
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) – without timing-out. (Default: 900, Min: 3, Max: 900)
memory_size (Optional[int]), The amount of memory (in MB) – (Default: 10240, Min: 128, Max: 10240)
tmp_size (Optional[int]) – (Default: 10240, Min: 512, Max: 10240).
retention_time (Optional[int]) The time (in days) – 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).
The resulting AWS Lambda Function object.
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.
Load existing Resource via its name.
name (str) – Name of the resource to load from name.
load_from_den (bool, optional) – Whether to try loading the module from Den. (Default: True)
dryrun (bool, optional) – Whether to construct the object or load as dryrun. (Default: False)
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]
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]
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.
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:
Specify the profile name in your code editor:
Install the AWS Toolkit extension.
Choose the relevant profile (e.g. profile lambda) and region (e.g us-east-1).
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.