Registry / aws / simpleflow

simpleflow

JSON →
library0.36.0pypypi✓ verified 22d ago

Simpleflow is a Python library for dataflow programming with Amazon Simple Workflow Service (SWF). It provides a Pythonic way to define and execute complex, distributed workflows by orchestrating activities and managing their states. The current version is 0.34.2, and it typically sees infrequent, but targeted, updates.

pip install simpleflow
INSTALL
IMPORT
SIG · SIMPLEFLOW
S
simpleflow
awspythonv0.36.0
Install
5.2s avg
Import
1001ms
Disk
62MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.034s · 62.4MB
glibc
py 3.103.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!")
Debug
Known issues
breakingPython 2 support has been dropped. Versions of simpleflow 0.30.0 and above require Python 3.7 or newer.
fix
Upgrade your Python environment to 3.7+ and ensure all project dependencies are compatible.
affects: <0.30.0
gotchaSimpleflow relies on `boto3` for AWS interaction, which requires proper AWS credentials and region configuration. Issues with these can lead to `ClientError` or `NoCredentialsError`.
fix
Ensure AWS credentials are configured via environment variables (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`), shared credential files (`~/.aws/credentials`, `~/.aws/config`), or IAM roles for EC2 instances.
affects: All
gotchaAWS SWF domains and task lists must be pre-created and configured in your AWS account before simpleflow can use them. If they don't exist, workflow/activity workers will fail to poll tasks.
fix
Manually create the necessary SWF domains and register workflow/activity types, or use automation scripts provided by simpleflow (e.g., `simpleflow swf --domain my-domain deploy my_workflow.py`).
affects: All
gotchaSimpleflow activities return `Future` objects. Directly accessing `.result` on a `Future` before the associated activity completes will either block indefinitely (in some executors) or raise an exception (in others).
fix
Use `simpleflow.futures.wait()` or ensure the `Future` is handled correctly within the workflow's execution context before attempting to retrieve its result. The local executor often resolves futures synchronously, but this behavior differs with the SWF executor.
affects: All
gotchaData passed between activities and workflows (inputs/outputs) must be JSON-serializable. Complex or custom Python objects will cause serialization errors unless custom encoders are used or data is converted to a compatible format.
fix
Convert complex objects to JSON-compatible types (dicts, lists, primitives) before passing them as activity/workflow inputs or returning them as outputs. Avoid passing large payloads due to AWS SWF limits.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'simpleflow'
The `simpleflow` library is not installed in the current Python environment.
fix
pip 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`.
fix
from 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`.
fix
from 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.
fix
Ensure 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.
Agent activity
22 hits · last 30 days
node
16
OpenAI (training)
1
Resources
simpleflow — pip install simpleflow · libregistry