Heaviside is a domain specific language (DSL) and Python compiler / support libraries for working with AWS StepFunctions.
The reason for a StepFunctions DSL is that the state machine language, while flexible, is hard to write and maintain. The DSL provides a simplied format for writing StepFunction state machines and serveral of common flow control statements.
The StepFunctionDSL document describes the Heaviside DSL.
In this document .hsd will be used to denote a StepFunction file written in
the Heaviside DSL. The extension .sfn will be used to denote a StepFunction
file written in the AWS state machine language.
pip install heavisideThe Heaviside package installs a script called heaviside that provides a CLI
to the library. Running the command without arguments or with the --help or
-h flag will provide detailed help.
All sub-commands (except compile) connect to AWS to manipulate StepFunctions.
There are multiple ways to define the AWS credentials, listed in the order of
precedence.
The compile sub-command doesn't connect to AWS, but does use the region and
account_id values when resolving Task ARNs. If the Heaviside DSL file has full
Task ARNs or the compiled file will not be uploaded to AWS these values can be
blank.
Note: Since compile doesn't connect to AWS, only the first two options in
the list above are valid for passing the region and account_id value.
To compile a Heaviside file into a AWS StepFunction file use the compile
sub-command.
$ heaviside compile state_machine.hsd -o state_machine.sfn The heaviside script can compile and upload the resulting file to AWS.
$ heaviside create state_machine.hsd AwsIamStepFunctionRoleArguments:
state_machine.hsd: The path to the Step Function definition written in the
Heaviside DSL.AwsIamStepFunctionRole: The AWS IAM Role that the StepFunction will use
when executing. Most often this will be used to
control which Lambdas and Activities the
StepFunction has permission to execute.The heaviside script can update an existing Step Function definition and / or
IAM role in AWS.
$ heaviside update state_machine --file state_machine.hsd --role AwsIamStepFunctionRoleArguments:
state_machine: Name of the state machine to updatestate_machine.hsd: The path to the Step Function definition written in the
Heaviside DSL.AwsIamStepFunctionRole: The AWS IAM Role that the StepFunction will use
when executing. Most often this will be used to
control which Lambdas and Activities the
StepFunction has permission to execute.The delete sub-command can be used to delete an existing StepFunction
$ heaviside delete state_machineThe start sub-command can be used to start executing a StepFunction.
$ heaviside start --json "{}" state_machineNote: By default the start sub-command will wait until the
execution has finished and will print the output of the StepFunction.
The Heaviside package installs the Python library heaviside. The public
API is documented in the Library API file.
Currently Heaviside has only been tested with Python 2.7 and 3.5.
Use or redistribution of the Boss system in source and/or binary forms, with or without modification, are permitted provided that the following conditions are met: