{"id":4258,"library":"simpleflow","title":"Simpleflow (AWS SWF)","description":"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.","status":"active","version":"0.34.2","language":"en","source_language":"en","source_url":"https://github.com/botify-labs/simpleflow","tags":["AWS","SWF","workflow","dataflow","orchestration","distributed-systems"],"install":[{"cmd":"pip install simpleflow","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for interaction with Amazon Web Services (AWS) SWF, SQS, S3, and CloudWatch.","package":"boto3","optional":false},{"reason":"Provides a robust concurrent execution framework, handling thread and process pools.","package":"futures-executor","optional":false},{"reason":"Used for scheduling and evaluating recurring events within workflows.","package":"croniter","optional":true},{"reason":"Provides process and system utility functions, potentially used for monitoring in certain executors.","package":"psutil","optional":true}],"imports":[{"symbol":"Workflow","correct":"from simpleflow.workflow import Workflow"},{"symbol":"activity","correct":"from simpleflow import activity"},{"symbol":"futures","correct":"from simpleflow import futures"},{"symbol":"with_attributes","correct":"from simpleflow.activity import with_attributes"}],"quickstart":{"code":"import os\nimport simpleflow\nfrom simpleflow import workflow, activity, futures\nfrom simpleflow.local.executor import Executor\n\n# Define an activity\n@activity.with_attributes(task_list='my_activity_task_list', version='1.0')\ndef say_hello(name):\n    \"\"\"An activity that returns a greeting.\"\"\"\n    print(f\"Activity 'say_hello' received: {name}\")\n    return f\"Hello, {name}!\"\n\n# Define a workflow\n@workflow.with_attributes(task_list='my_workflow_task_list', version='1.0')\nclass GreetingWorkflow(workflow.Workflow):\n    \"\"\"A simple workflow that uses the say_hello activity.\"\"\"\n    def __init__(self):\n        super(GreetingWorkflow, self).__init__()\n        # Bind the activity to the workflow instance\n        self.say_hello_activity = say_hello\n\n    def run(self, name):\n        print(f\"Workflow 'GreetingWorkflow' started with input: {name}\")\n        # Schedule the activity and get a Future object\n        hello_future = self.say_hello_activity(name)\n\n        # In a real SWF execution, futures.wait() would block until the activity completes.\n        # For the local executor, the result is often resolved synchronously.\n        # Accessing .result will retrieve the value when ready.\n        final_greeting = hello_future.result\n        print(f\"Workflow received result from activity: {final_greeting}\")\n        return final_greeting\n\n# --- Quickstart Execution (using local executor for demonstration) ---\nif __name__ == \"__main__\":\n    # The local executor allows running workflows without connecting to AWS SWF.\n    # It executes activities and workflows synchronously in the same process.\n    executor = Executor()\n    print(\"\\n--- Executing GreetingWorkflow locally ---\")\n\n    # Run the workflow. Arguments to the workflow's `run` method are passed as a tuple.\n    # The executor's `run` method returns the final result of the workflow.\n    workflow_input_name = \"Simpleflow User\"\n    final_output = executor.run(GreetingWorkflow, (workflow_input_name,))\n\n    print(f\"\\n--- Workflow Execution Complete ---\")\n    print(f\"Input name: '{workflow_input_name}'\")\n    print(f\"Final output: '{final_output}'\")\n\n    assert final_output == f\"Hello, {workflow_input_name}!\"\n    print(\"Local execution successful!\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.7+ and ensure all project dependencies are compatible.","message":"Python 2 support has been dropped. Versions of simpleflow 0.30.0 and above require Python 3.7 or newer.","severity":"breaking","affected_versions":"<0.30.0"},{"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.","message":"Simpleflow relies on `boto3` for AWS interaction, which requires proper AWS credentials and region configuration. Issues with these can lead to `ClientError` or `NoCredentialsError`.","severity":"gotcha","affected_versions":"All"},{"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`).","message":"AWS 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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Simpleflow 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).","severity":"gotcha","affected_versions":"All"},{"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.","message":"Data 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}