Install & Compatibility
Where this runs
tested against v0.36.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.034s · 62.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.2s · import 0.968s · 63MB
62MB installed
● package 62MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Workflow
✓ from simpleflow.workflow import Workflow
activity
✓ from simpleflow import activity
futures
✓ from simpleflow import futures
with_attributes
✓ from simpleflow.activity import with_attributes
This quickstart defines a simple activity and a workflow using `simpleflow`. It then demonstrates how to run this workflow locally using `simpleflow.local.executor.Executor`, which allows testing without needing an AWS SWF backend.
import os
import simpleflow
from simpleflow import workflow, activity, futures
from simpleflow.local.executor import Executor
# Define an activity
@activity.with_attributes(task_list='my_activity_task_list', version='1.0')
def say_hello(name):
"""An activity that returns a greeting."""
print(f"Activity 'say_hello' received: {name}")
return f"Hello, {name}!"
# Define a workflow
@workflow.with_attributes(task_list='my_workflow_task_list', version='1.0')
class GreetingWorkflow(workflow.Workflow):
"""A simple workflow that uses the say_hello activity."""
def __init__(self):
super(GreetingWorkflow, self).__init__()
# Bind the activity to the workflow instance
self.say_hello_activity = say_hello
def run(self, name):
print(f"Workflow 'GreetingWorkflow' started with input: {name}")
# Schedule the activity and get a Future object
hello_future = self.say_hello_activity(name)
# In a real SWF execution, futures.wait() would block until the activity completes.
# For the local executor, the result is often resolved synchronously.
# Accessing .result will retrieve the value when ready.
final_greeting = hello_future.result
print(f"Workflow received result from activity: {final_greeting}")
return final_greeting
# --- Quickstart Execution (using local executor for demonstration) ---
if __name__ == "__main__":
# The local executor allows running workflows without connecting to AWS SWF.
# It executes activities and workflows synchronously in the same process.
executor = Executor()
print("\n--- Executing GreetingWorkflow locally ---")
# Run the workflow. Arguments to the workflow's `run` method are passed as a tuple.
# The executor's `run` method returns the final result of the workflow.
workflow_input_name = "Simpleflow User"
final_output = executor.run(GreetingWorkflow, (workflow_input_name,))
print(f"\n--- Workflow Execution Complete ---")
print(f"Input name: '{workflow_input_name}'")
print(f"Final output: '{final_output}'")
assert final_output == f"Hello, {workflow_input_name}!"
print("Local execution successful!")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'simpleflow'
The `simpleflow` library is not installed in the current Python environment.
fixpip install simpleflow
ImportError: cannot import name 'get_workflow_definition' from 'simpleflow.swf'
The `get_workflow_definition` helper function is not directly exposed from the `simpleflow.swf` module; in simpleflow v0.34.2, it resides in `simpleflow.utils`.
fixfrom simpleflow.utils import get_workflow_definition
AttributeError: 'function' object has no attribute 'with_attributes'
The `activity` decorator (from `simpleflow.activity`) is a function, and `with_attributes` (from `simpleflow.decorators`) is a separate decorator. They cannot be chained using dot notation like `activity.with_attributes`.
fixfrom simpleflow.activity import activity
from simpleflow.decorators import with_attributes
@with_attributes(my_attribute='value')
@activity
def my_activity_function():
pass botocore.exceptions.ClientError: An error occurred (InvalidAccessKeyId) when calling the GetWorkflowExecution operation: The Access Key ID provided does not exist in our records.
Simpleflow relies on AWS credentials and region being correctly configured for `boto` or `boto3`. This error indicates that the configured AWS access keys are invalid or missing.
fixEnsure AWS credentials (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) and default region (e.g., `AWS_DEFAULT_REGION`) are set in your environment variables, or configured in `~/.aws/credentials` and `~/.aws/config` files.
Upgrade
Version history
0.36.0latest on PyPI · released Jul 1, 2026
Audit
Dependencies
boto3requiredRequired for interaction with Amazon Web Services (AWS) SWF, SQS, S3, and CloudWatch.
futures-executorrequiredProvides a robust concurrent execution framework, handling thread and process pools.
croniteroptionalUsed for scheduling and evaluating recurring events within workflows.
psutiloptionalProvides process and system utility functions, potentially used for monitoring in certain executors.