Skip to main content

Python SDK API guidance

Welcome to the Resonate Python SDK guide! This SDK makes it possible to write Distributed Async Await applications with Python. This guide covers installation and features that the SDK offers.

API Reference

Looking for the API reference?

The Resonate Python SDK API reference is available here.

Installation​

How to install the Resonate Python SDK into your project.

To install the Resonate Python SDK, you can use any of your favorite package managers.

uv add resonate-sdk

Initialization​

How to initialize a Resonate Client.

There are two ways to initialize Resonate, local and remote.

Local initialization = zero-dependency development

Local initialization means that Resonate uses local memory for promise storage.

This is ideal for getting started quickly or for integrating Resonate into an existing application without relying on dependencies.

from resonate import Resonate

resonate = Resonate()

# or alternatively
resonate = Resonate.local()
Dead Simple incremental adoption

Temporal, Restate, and DBOS require a server or database to get started.

Resonate enables you to get started with a local worker that stores promises in memory, no server or database required. This makes it easy to incrementally adopt Resonate into your existing Python application.

Remote initialization

Remote initialization means that promises are stored remotely, and that the Resonate Client receives messages from a remote source. This is how Resonate enables Durable Async RPC for building distributed applications that are reliable and scalable.

The quickest way to get started with Remote initialization is to connect to a locally running instance of a Resonate Server.

from resonate import Resonate

resonate = Resonate.remote()

The default configuration uses the Resonate Server as the promise store and uses an HTTP Long Poller as the message transport to receive messages directly from the Resonate Server.

A Resonate Client can receive messages from many different transports, such as HTTP, RabbitMQ, RedPanda, etc... The Poller is a great starting place however, as it will long-poll for messages from the Resonate Server without any additional setup.

Environment Variables​

Environment variables can be used to configure the Resonate Client. These environment variables follow the following priority pattern:

Explicit parameter passed to constructor (highest priority) Service-specific environment variable (e.g., RESONATE_HOST_STORE) Generic environment variable (e.g., RESONATE_HOST) Default hardcoded value (lowest priority)

RESONATE_HOST​

Generic fallback host for Resonate services.

Defaults to "http://localhost".

RESONATE_HOST_STORE​

Specific host for the Store service.

Defaults to RESONATE_HOST, then "http://localhost".

RESONATE_HOST_MESSAGE_SOURCE​

Specific host for the Message Source service.

Defaults to RESONATE_HOST, then "http://localhost".

RESONATE_PORT_STORE​

Port for the Store service

Defaults to port "8001", the default port exposed by the Resonate Server Store service.

RESONATE_PORT_MESSAGE_SOURCE​

Port for the Message Source service

Defaults to port "8002", the default port exposed by the Resonate Server Message Source service.

RESONATE_USERNAME​

Username for HTTP Basic Authentication

Defaults to "" (empty string) if variable exists, None if not set.

RESONATE_PASSWORD​

Password for HTTP Basic Authentication

Defaults to "" (empty string) if RESONATE_USERNAME exists, None otherwise.

Client APIs​

Registration

How to register a function with Resonate in the Python SDK.

There are two ways to register a function with Resonate: using the register() method or using the @resonate.register decorator.

@resonate.register​

Decorator

@resonate.register
def foo(ctx, arg):
    # ...
    return result

.register()​

Method

def foo(ctx, arg):
    # ...
    return result

resonate.register(foo)

.set_dependency()​

Resonate's .set_dependency() method allows you to set a dependency for the Application Node. You can then access the dependency in the function using the .get_dependency() method.

Dependencies can only be added in the ephemeral world.

resonate.set_dependency("dependency-name", dependency)

The dependency can be accessed from any function in the Call Graph on that Application Node. This is useful for things like database connections or other resources that you want to share across functions.

How to invoke a function in the ephemeral world with the Resonate Class.

To move from the ephemeral world to the durable world you use the Resonate Class to invoke functions.

There are two methods that you can use: .run() and .rpc().

.run()​

Resonate's .run() method invokes a function in the same process and returns the result. You can think of it as a "run right here" invocation. After invocation, the function is considered durable and will recover in another process if required.

result = resonate.run("invocation-id", foo, arg)

.begin_run()​

Similar to .run() but instead of returning the result, returns a handle so the result can be awaited later.

handle = resonate.begin_run("invocation-id", foo, arg)
result = handle.result()

.rpc()​

Resonate's .rpc() method (Remote Procedure Call) invokes a function in a remote process and returns the result. You can think of it as a "run somewhere else" invocation (Asynchronous Remote Procedure Call). After invocation, the function is considered durable and will recover in another process if required.

result = resonate.rpc("invocation-id", "foo", args)

# optionally target a specific group
result = resonate.options(target="poll://any@workers").rpc("invocation-id", "foo", args)

.begin_rpc()​

Similar to .rpc() but instead of returning the result, returns a handle so the result can be awaited later.

handle = resonate.begin_rpc("invocation-id", "foo", arg)
result = handle.result()

.options()​

Options can be used preceding .run(), .beginRun(), .rpc(), and .beginRpc().

from resonate.retry_policies import Exponential, Constant, Linear, Never

resonate.options(
    idempotency_key="custom-ikey",
    retry_policy=Exponential(), # or Constant(), Linear(), Never()
    target="poll://any@workers",
    tags={"key": "value"},
    timeout=60.0, # 1 minute in seconds
    version=1,
).run("invocation-id", foo, arg)

.get()​

Resonate's .get() method allows you to subscribe to a function invocation. If the function invocation does not exist, an error will be thrown.

handle = resonate.get("invocation-id")
result = handle.result()

.promises.get()​

Resonate's .promises.get() method allows you to get a promise by ID.

resonate.promises.get("promise-id")

.promises.create()​

Resonate's .promises.create() method allows you to create a promise.

resonate.promises.create(
    id="promise-id",
    timeout=int(time.time() * 1000) + 30000,  # 30s in the future
)

.promises.resolve()​

Resonate's .promises.resolve() method allows you to resolve a promise by ID.

This is useful for HITL use cases where you want to wait for a human to approve or reject a function execution. It works well in conjunction with the .promise() method.

resonate.promises.resolve(
    id="promise-id",
    data=json.dumps({}),  # optional
)

.promises.reject()​

Resonate's .promises.reject() method allows you to reject a promise by ID.

resonate.promises.reject(
    id="promise-id",
    data=json.dumps({}),  # optional
)

Context APIs​

How to use the Resonate Context object in the Python SDK.

Resonate's Context object enables you to invoke functions from inside a Durable Function. This is how you extend the Call Graph and create a world of Durable Functions. Inside a Durable Function you use the yield keyword to interact with the Context object.

.get_dependency()​

Context's .get_dependency() method allows you to get a dependency that was set in the ephemeral world using the .set_dependency() method and use it the Durable World.

@resonate.register
def foo(ctx, arg):
    # ...
    dependency = ctx.get_dependency("dependency-name")
    # do something with the dependency
    # ...

.run()​

Context's .run() method invokes a function in the same process in a synchronous manner. That is — the calling function blocks until the invoked function returns.

@resonate.register
def foo(ctx, arg):
    # ...
    result = yield ctx.run(bar, arg)
    # do more stuff
    # ...


def bar(ctx, arg):
    # ...
    return

.begin_run()​

Context's .begin_run() method invokes a function in the same process in an asynchronous manner. That is — the invocation returns a promise which can be awaited later.

@resonate.register
def foo(ctx, arg):
    # ...
    promise = yield ctx.begin_run(bar, arg)
    # do more sture
    result = yield promise
    # ...


def bar(ctx, arg):
    # ...
    return

.rpc()​

The RPC API is how you durably communicate between processes. Its how you invoke functions in other processes and extend the Call Graph across process boundaries.

RPC is synchronous, and blocks the calling function until the invoked function returns. Begin RPC is asynchronous, and returns a promise which can be awaited later.

# process x
@resonate.register
def foo(ctx: Context, arg: str) -> str:
    # synchronous invocation of bar
    result = yield ctx.rpc("bar", arg)
    # do more stuff
    result = yield promise


# process y
@resonate.register
def bar(ctx: Context, arg: str) -> str:
    # ...
    return

.begin_rpc()​

Context's .begin_rpc() method invokes a function in a remote process in an asynchronous manner. That is — the invocation returns a promise which can be awaited on later.

# process a
@resonate.register
def foo(ctx, arg):
    # ...
    promise = yield ctx.begin_rpc("bar", arg)
    # do more stuff
    result = yield promise
    # ...

# process b
@resonate.register
def bar(ctx, arg):
    # ...
    return

.detached()​

Context's .detached() method invokes a function in a remote process in an asynchronous manner but unlike .begin_rpc(), the promise is not implictly awaited. Use .detached() when you want to fire-and-forget a function invocation.

@resonate.register
def foo(ctx, arg):
    # ...
    yield ctx.detached("bar", arg)
    # do more stuff
    # ...

.options()​

Options can be used following .run(), .beginRun(), .rpc(), .beginRpc(), and .detached().

from resonate.retry_policies import Exponential, Constant, Linear, Never

@resonate.register
def foo(ctx, arg):
    # ...
    yield ctx.run(bar, arg).options(
        id="custom-id",
        idempotency_key="custom-ikey",
        durable=True,
        retry_policy=Exponential(), # or Constant(), Linear(), Never()
        target="poll://any@workers",
        tags={"key": "value"},
        timeout=30.0,
        version=1,
    )

.promise()​

Context's .promise() method allows you to get or create a promise that can be awaited on.

If no ID is provided, one is generated and a new promise is created. If an ID is provided and a promise already exists with that ID, then the existing promise is returned (if the idempotency keys match).

This is very useful for HITL (Human-In-The-Loop) use cases where you want to block progress until a human has taken an action or provided data. It works well in conjunction with the .promises.resolve() method.

@resonate.register
def foo(ctx, arg):
    # ...
    promise = yield ctx.promise(id="promise-id")
    # do more stuff
    result = yield promise
    # ...

You can also pass custom data into the promise.

@resonate.register
def foo(ctx, arg):
    # ...
    promise = yield ctx.promise(data={"key": "value"})
    # do more stuff
    result = yield promise
    # ...

.sleep()​

Context's .sleep() method allows you to sleep inside a function. There is no limit to how long you can sleep. The sleep method accepts a float value in seconds.

@resonate.register
def foo(ctx, arg):
    # ...
    yield ctx.sleep(5.0) // sleep for 5 seconds
    # do more stuff
    # ...

.time.time()​

Context's .time.time() method allows you to deterministically get the time in seconds since the epoch. If your function execution is recovered after the time has been retrieved, the same time will be returned. This is helpful for ensuring the same code path is taken in the event of a recovery.

@resonate.register
def foo(ctx, arg):
    # ...
    time = yield ctx.time.time()
    # do something with time
    # ...

.random.random()​

Context's .random.random() method allows you to generate a deterministic random number. If your function execution is recovered after the random number has been generated, the same number will be returned. This is helpful for ensuring the same code path is taken in the event of a recovery.

@resonate.register
def foo(ctx, arg):
    # ...
    rand = yield ctx.random.random()
    # do something with rand
    # ...

.options()​

Many of Context's methods support options on the call you are making.