Workflows SDK for Python

Render Workflows is in public beta.

During the beta, bugs or changes in API/SDK behavior are possible as we continue refining the product. We welcome any and all feedback at workflows-feedback@render.com.

The Render SDK for Python provides support for:

Defining workflow tasks
Triggering runs of those tasks from your other Python code

When triggering runs, you use different classes for asynchronous and synchronous execution contexts.

From your Python project directory:

If you already have the SDK installed, make sure you're using version 0.6.0 or later:

After installing, make sure to add render_sdk>=0.6.0 as a dependency in your application's requirements.txt, pyproject.toml, or equivalent.

The following symbols pertain to creating and registering tasks in your workflow service. For guidance on how to use them, see Defining Workflow Tasks.

Handles defining and registering workflow tasks. Initialize this in each file where you define tasks.

Initializes a new Workflows object. All arguments are optional.

Initializes a new Workflows object that incorporates tasks from one or more other Workflows objects.

Use this in your workflow's entry point file if you import task definitions from other files:

If you set any defaults with this method (such as default_timeout), those defaults apply only to tasks registered directly on this object (not to tasks registered on the imported objects).

You apply the @app.task decorator to a Python function to register it as a workflow task. For details, see Defining Workflow Tasks

The app.start() method serves as the entry point for your workflow during both task registration and run execution. Your workflow definition must call this method as part of startup:

This method takes no arguments.

Use the RenderAsync class to trigger and manage task runs from any asynchronous execution context (such as a FastAPI route handler). All methods are async and return awaitable objects.

Initializes a new RenderAsync object. All arguments are optional.

These methods are available on the workflows attribute of the RenderAsync class.

Kicks off a run of the registered task with the specified identifier, passing the specified arguments.

To instead run a task and wait for it to complete, use workflows.run_task.

On success: Returns an AwaitableTaskRun object representing the initial state of the task run. You can await this object to wait for the run to complete.

Raises: ClientError, ServerError, TimeoutError

Starts the registered task with the specified identifier, waits for it to complete, and returns the result.

To instead kick off a run without waiting for it to complete, use workflows.start_task.

On success: Returns a TaskRunDetails object for the completed task run.

Raises: ClientError, ServerError, TimeoutError, TaskRunError

Lists task runs that match optional filters specified in the provided ListTaskRunsParams object.

On success: Returns a list of TaskRun objects.

Raises: ClientError, ServerError, TimeoutError

Supported fields of the ListTaskRunsParams object include:

Retrieves the details of the task run with the specified ID.

On success: Returns a TaskRunDetails object.

Raises: ClientError, ServerError, TimeoutError

Cancels the task run with the specified ID. This raises a ClientError if the task run is not found, or if it isn't currently running.

On success: Returns None.

Raises: ClientError, ServerError, TimeoutError

Streams completion events for one or more task runs via Server-Sent Events (SSE). Returns an async iterator that yields a TaskRunDetails object each time a specified task run completes or fails.

The connection stays open until all events are received or you break out of the loop.

Raises: ClientError, ServerError, TimeoutError

Represents the initial state of a task run as returned by the async workflows.start_task method.

You can await this object to wait for the task run to complete. On success, it returns a TaskRunDetails object:

If the task run fails, this await raises a TaskRunError exception.

Use the Render class in any synchronous execution context (such as a default Flask or Django app). All methods are blocking.

Initializes a new Render object. All arguments are optional.

These methods are available on the workflows attribute of the Render class.

Runs the registered task with the specified identifier, passing the specified arguments.

To instead run a task and wait for it to complete, use workflows.run_task.

On success: Returns a TaskRun object representing the initial state of the task run (e.g. id, status). To wait for completion, poll workflows.get_task_run or use workflows.run_task.

Raises: ClientError, ServerError, TimeoutError

Starts the task, waits for it to complete, and returns the result.

To instead kick off a run without waiting for it to complete, use workflows.start_task.

On success: Returns a TaskRunDetails object.

Raises: ClientError, ServerError, TimeoutError, TaskRunError

Lists task runs that match optional filters.

On success: Returns a list of TaskRun objects.

Raises: ClientError, ServerError, TimeoutError

Supported fields: limit, cursor, owner_id. See workflows.list_task_runs for parameter descriptions.

Retrieves the details of the task run with the specified ID.

On success: Returns a TaskRunDetails object.

Raises: ClientError, ServerError, TimeoutError

Cancels the task run. Raises ClientError if not found or not running.

On success: Returns None.

Raises: ClientError, ServerError, TimeoutError

Streams completion events via SSE. Returns a synchronous iterator that yields a TaskRunDetails object each time a specified task run completes or fails.

Raises: ClientError, ServerError, TimeoutError

Summarizes the state of a task run. Obtained in one of the following ways:

From the sync workflows.start_task method
Calling the workflows.list_task_runs method (sync or async)

To get a run's full details including results, call workflows.get_task_run (sync or async) and provide the run's ID to obtain a TaskRunDetails object.

Provides the full details of a task run. Obtained in one of the following ways:

awaiting an AwaitableTaskRun object returned by the async workflows.start_task method:
Calling the workflows.run_task method of the Render or RenderAsync class:
Calling the workflows.get_task_run method of the Render or RenderAsync class:
Iterating over events from the workflows.task_run_events method of the Render or RenderAsync class:

A TaskRunDetails object includes all of the same properties as a TaskRun object, plus:

Exceptions raised by the SDK have one of the types listed below. RenderError is the parent class for all other exception types.