adamgilman / stairstep

A Pythonic API for Amazon's States Language for defining AWS Step Functions

stairstep

StairStep is a Pythonic API for designing AWS Step Functions using Amazon's State Language

Instead of hand crafting JSON, StairStep allows you define step functions using Python code which allows you to easily import information from outside sources and dynamically create step functions on the fly.

Development Progress / Coverage

Lanuage Feature	Type	Progress
State	Pass	✅
State	Task	✅
State	Succeed	✅
State	Fail	✅
State	Choice	✅
Field	Common Validations	✅
State	Wait	✅
State	Parallel	Next 🛣

Examples

• Hello World
• Complex Choice State

Hello World

Using the example from the Amazon's State Language page

{
    "Comment": "A simple minimal example of the States language",
    "StartAt": "Hello World",
    "States": {
    "Hello World": { 
      "Type": "Task",
      "Resource": "arn:aws:lambda:us-east-1:123456789012:function:HelloWorld",
      "End": true
    }
  }
}

We can easily craft that in StairStep as follows

# Create a parent StairStep object
ss = StairStep(comment="A simple minimal example of the States language", startAt="Hello World")

# Create the HelloWorld step
hello = StateTask(name="Hello World", resource="arn:aws:lambda:us-east-1:123456789012:function:HelloWorld", end=True)

# Add the step into the StairStep object
ss.addState(hello)

# Create the Amazon State Language Export
ss.json()

{  
   "Comment":"A simple minimal example of the States language",
   "StartAt":"Hello World",
   "States":{  
      "Hello World":{  
         "Type":"Task",
         "Resource":"arn:aws:lambda:us-east-1:123456789012:function:HelloWorld",
         "End":true
      }
   }
}

Complex Choice State

ss = StairStep(
    comment = "Example Choice State",
    startAt = "ChoiceStateX"
)
# Create a ChoiceRule, which is composed of choice expression(s)
# This checks to see if the variable $.type is not "Private"
typeNotPrivate = ChoiceRule(operator="Not", snext="Public", conditions=
    ChoiceExpression(operator="StringEquals", variable="$.type", value="Private")
)

# This checks to see if the value of $.value is >=20 or <30
valueInTwenties = ChoiceRule(operator="And", snext="ValueInTwenties", conditions=
    [
        ChoiceExpression(operator="NumericGreaterThanEquals", variable="$.value", value=20),
        ChoiceExpression(operator="NumericLessThan", variable="$.value", value=30)
    ]
)
state = StateChoice(name="ChoiceStateX", choices=[typeNotPrivate,valueInTwenties],default="DefaultState")

default = StatePass(name="DefaultState", end=True)
in_twenties = StatePass(name="ValueInTwenties", end=True)
public = StatePass(name="Public", end=True)

ss.addState(state)
ss.addState(in_twenties)
ss.addState(public)
ss.addState(default)
ss.json()

{
	"Comment": "Example Choice State",
	"StartAt": "ChoiceStateX",
	"States": {
		"ChoiceStateX": {
			"Type": "Choice",
			"Default": "DefaultState",
			"Choices": [{
				"Next": "Public",
				"Not": {
					"Variable": "$.type",
					"StringEquals": "Private"
				}
			}, {
				"Next": "ValueInTwenties",
				"And": [{
					"Variable": "$.value",
					"NumericGreaterThanEquals": 20
				}, {
					"Variable": "$.value",
					"NumericLessThan": 30
				}]
			}]
		},
		"ValueInTwenties": {
			"Type": "Pass",
			"End": true
		},
		"Public": {
			"Type": "Pass",
			"End": true
		},
		"DefaultState": {
			"Type": "Pass",
			"End": true
		}
	}
}

stairstep's Issues

StatePass has no validations

from stairstep import StateChoice, ChoiceRule, ChoiceExpression, StatePass

# Create a ChoiceRule, which is composed of choice expression(s)
# This checks to see if the variable $.type is not "Private"
typeNotPrivate = ChoiceRule(operator="Not", snext="Public", conditions=
    ChoiceExpression(operator="StringEquals", variable="$.type", value="Private")
)

# This checks to see if the value of $.value is >=20 or <30
valueInTwenties = ChoiceRule(operator="And", snext="ValueInTwenties", conditions=
    [
        ChoiceExpression(operator="NumericGreaterThanEquals", variable="$.value", value=20),
        ChoiceExpression(operator="NumericLessThan", variable="$.value", value=30)
    ]
)
state = StateChoice(name="ChoiceStateX", choices=[typeNotPrivate,valueInTwenties],default="DefaultState")

default = StatePass(name="DefaultState", end=True)
in_twenties = StatePass(name="ValueInTwenties", end=True)
public = StatePass(name="Public", end=True)

ss.addState(state)
ss.addState(in_twenties)
ss.addState(public)
ss.json()


>>> ss.json()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/dev2/Desktop/WORKING/stairstep/stairstep/base.py", line 100, in json
    return json.dumps( self.export() )
  File "/Users/dev2/Desktop/WORKING/stairstep/stairstep/base.py", line 85, in export
    states[k] = self.states[k].export()
  File "/Users/dev2/Desktop/WORKING/stairstep/stairstep/base.py", line 14, in export
    self.validate()
  File "/Users/dev2/Desktop/WORKING/stairstep/stairstep/base.py", line 9, in validate
    all_validations = self.base_validations + self.validations
AttributeError: 'StatePass' object has no attribute 'validations'

New PIP release ?

I need Parameters option and SAM CLI build command doesn't work very well with git dependencies. @adamgilman Could you please make a new release?

State: Parallel

Better readme with examples

Explain choice operators better
Replace header image
walk through examples explaining each concept

Retry logic

PyPi setup and upload

StateTask export is not idempotent

.json()
.json()

gives attribute error

Improve method signatures for State classes

For IDE/help() purposes improve how the function signatures appear

https://www.reddit.com/r/Python/comments/958iq9/besides_wrapper_functions_when_is_it_a_smart_idea/e3r6fss/

add pre-commit PEP checker

CircleCI needs to be on Python3

State: Wait

Replace JSON engine with QuickType?

Reimplement the JSON creation portion with QuickType or something similar?