api_futures.rst

Lithops Core API

The core abstraction in Lithops is the executor, which is responsible for orchestrating the execution of your functions across different environments.

To get started, you typically import lithops and create an executor instance to run your code. Lithops provides a flexible set of executors to suit different needs.

Primary Executors

• FunctionExecutor (lithops.FunctionExecutor()): The main, generic executor that automatically selects its execution mode based on the provided configuration. This lets you write your code once and run it seamlessly on localhost, serverless, or standalone backends without changing your code.
• RetryingFunctionExecutor (lithops.RetryingFunctionExecutor()): A robust wrapper around FunctionExecutor that transparently handles retries on failed tasks. It supports the features of FunctionExecutor with added automatic retry logic, improving fault tolerance and reliability for unstable or transient-failure-prone environments. A failed call is retried with its own input: a bucket, prefix or directory passed to a function that processes objects is retried one object, or one chunk of an object, at a time.

Secondary Executors

For more specialized use cases, Lithops also provides explicit executors for each execution mode:

• LocalhostExecutor (lithops.LocalhostExecutor()): Runs jobs locally using multiple processes on your machine. Ideal for development, debugging, or small-scale workloads.
• ServerlessExecutor (lithops.ServerlessExecutor()): Executes jobs on serverless compute platforms, managing scaling and deployment automatically. Best for massively parallel, ephemeral workloads.
• StandaloneExecutor (lithops.StandaloneExecutor()): Runs jobs on standalone compute backends such as clusters or virtual machines. Suitable for long-running or resource-heavy tasks.

Configuration and Initialization

By default, executors load configuration from the Lithops configuration file (e.g., ~/.lithops/config). You can also supply configuration parameters programmatically via a Python dictionary when creating an executor instance. Parameters passed explicitly override those in the config file, allowing for flexible customization on the fly.

This layered executor design lets Lithops provide a powerful, unified API for parallel function execution — from local development to multi-cloud production deployments, with fault tolerance and retries built in.

Core API Reference

.. automodule:: lithops.executors
   :members:
   :undoc-members:
   :show-inheritance:

.. autoclass:: lithops.retries.RetryingFunctionExecutor
   :members:
   :undoc-members:
   :show-inheritance:

map() and map_reduce() return a :class:`~lithops.utils.FuturesList`, which is a list of futures that can be mapped over again. A plain list or tuple of those futures is a chain too, including a slice or a comprehension. See :doc:`Function chaining <notebooks/function_chaining>`.

.. autoclass:: lithops.utils.FuturesList
   :members: map, map_reduce, wait, get_result
   :show-inheritance: