Create, run and manage AWS Step Functions easily

aws, sfn, service, step, functions, states, boto3, python, step-functions
pip install sfini==0.1.0



Build Status codecov Documentation Status Contributor Covenant

Create, run and manage AWS Step Functions easily. Pronounced "SFIN-ee".

This package aims to provide a user-friendly interface into defining and running Step Functions. Things you can do in sfini to interact with AWS Step Functions:

  • Implement and register activities
  • Define and register state machines
  • Start, track and stop executions
  • Run workers for activities
  • Get information for registered activities and state machines
  • De-register state machines and activities

Note: this is not a tool to convert Python code into a Step Functions state machine. For that, see pyawssfn.

Getting started


  • AWS (Amazon Web Services) account, with access to Step Functions
  • AWS IAM (Identity and Access Management) credentials


pip install sfini



Check the documentation or use the built-in help:

pydoc sfini
import sfini

AWS Step Functions

AWS Step Functions (SFN) is a workflow-management service, providing the ability to coordinate tasks in a straight-forward fashion. Further documentation can be found in the AWS documentation.

Usage of Step Functions consists of two types: state-machines and activities. A state-machine is a graph of operations which defines a workflow of an application, comprised of multiple types of "states", or stages of the workflow. An activity processes input to an output, and is used to process a task "state" in the state-machine (multiple task states can have the same activity assigned it.

Once a state-machine is defined and registered (along with the used activities), you run executions of that state-machine on different inputs to run the workflow. sfini allows you to start, stop and get the history of these executions.

State-machines support conditional branching (and therefore loops), retries (conditional and unconditional), exception-catching, external AWS service support for running tasks, parallel execution and input/output processing. External services including AWS Lambda, so you don't have to deploy your own activity runners.

Once state-machines and activities are defined and registered, you can view and update their details in the SFN web console.

Role ARN

Every state-machine needs a role ARN (Amazon Resource Name). This is an AWS IAM role ARN which allows the state-machine to process state executions. See AWS Step Functions documentation for more information.


More examples found in the documentation.

import sfini

# Define activities
activities = sfini.ActivityRegistration(prefix="test")

def add_activity(data):
    return data["a"] + data["b"]

# Define state-machine
add = sfini.Task("add", add_activity)
sm = sfini.construct_state_machine("testAdding", add)

# Register state-machine and activities

# Start activity worker
worker = sfini.Worker(add_activity)

# Start execution
execution = sm.start_execution(execution_input={"a": 3, "b": 42})
# testAdding_2019-05-13T19-07_0354d790

# Wait for execution and print output
# 45
# ExecutionStarted [1] @ 2019-06-23 20:03:52.817000+10:00
# TaskStateEntered [2] @ 2019-06-23 20:03:52.840000+10:00:
#   name: add
# ActivityScheduled [3] @ 2019-06-23 20:03:52.840000+10:00:
#   resource: arn:aws:states:us-west-2:ACCID:activity:testaddActivity
# ActivityStarted [4] @ 2019-06-23 20:03:53.954000+10:00:
#   worker: hostname-3a4fb480
# ActivitySucceeded [5] @ 2019-06-23 20:03:55.028000+10:00
# TaskStateExited [6] @ 2019-06-23 20:03:55.028000+10:00:
#   name: add
# ExecutionSucceeded [7] @ 2019-06-23 20:03:55.028000+10:00
# Output: 45

# Stop activity workers

# Deregister state-machine and activities