{"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":"python","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,"search_vec":"'0.34.2':41 'activ':32 'amazon':13 'aw':2,50 'complex':27 'current':38 'dataflow':10,53 'defin':24 'distribut':28,56 'distributed-system':55 'execut':26 'infrequ':46 'librari':8 'manag':34 'orchestr':31,54 'program':11 'provid':19 'python':7,21 'see':45 'servic':16 'simpl':14 'simpleflow':1,4 'state':36 'swf':3,17,51 'system':57 'target':48 'typic':44 'updat':49 'version':39 'way':22 'workflow':15,29,52","created_at":"2026-04-12T03:47:41.556678+00:00","updated_at":"2026-04-16T21:45:20.573706+00:00","problems":[{"fix":"pip install simpleflow","cause":"The `simpleflow` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'simpleflow'"},{"fix":"from simpleflow.utils import get_workflow_definition","cause":"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`.","error":"ImportError: cannot import name 'get_workflow_definition' from 'simpleflow.swf'"},{"fix":"from simpleflow.activity import activity\nfrom simpleflow.decorators import with_attributes\n\n@with_attributes(my_attribute='value')\n@activity\ndef my_activity_function():\n    pass","cause":"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`.","error":"AttributeError: 'function' object has no attribute 'with_attributes'"},{"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.","cause":"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.","error":"botocore.exceptions.ClientError: An error occurred (InvalidAccessKeyId) when calling the GetWorkflowExecution operation: The Access Key ID provided does not exist in our records."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.36.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/botify-labs/simpleflow","docs":"https://botify-labs.github.io/simpleflow","changelog":"https://github.com/botify-labs/simpleflow/blob/main/CHANGELOG.md","pypi":"https://pypi.org/project/simpleflow/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["aws","workflow"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}