Package: heaviside
HeavisideHeaviside is a domain specific language (DSL) and Python compiler / support
libraries for working withAWS StepFunctions.WhyThe reason for a StepFunctions DSL is that thestate 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.DSLTheStepFunctionDSLdocument describes the Heaviside DSL.Getting StartedIn this document.hsdwill be used to denote a StepFunction file written in
the Heaviside DSL. The extension.sfnwill be used to denote a StepFunction
file written in the AWSstate machine language.Installingpip install heavisideCLI ScriptThe Heaviside package installs a script calledheavisidethat provides a CLI
to the library. Running the command without arguments or with the--helpor-hflag will provide detailed help.AWS CredentialsAll sub-commands (exceptcompile) connect to AWS to manipulate StepFunctions.
There are multiple ways to define the AWS credentials, listed in the order of
precedence.Explicitly pass the values as command line arguments or environmental variablesPass a file path to a JSON file with the argumentsLetting Boto3 try to resolve secret / access keysLooking at EC2 meta data for current AWS regionLooking at current IAM user for AWS account_idThecompilesub-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: Sincecompiledoesn't connect to AWS, only the first two options in
the list above are valid for passing the region and account_id value.CompilingTo compile a Heaviside file into a AWS StepFunction file use thecompilesub-command.$ heaviside compile state_machine.hsd -o state_machine.sfnCreating a StepFunctionTheheavisidescript can compile and upload the resulting file to AWS.$ heaviside create state_machine.hsd AwsIamStepFunctionRoleArguments: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.Deleting a StepFunctionThedeletesub-command can be used to delete an existing StepFunction$ heaviside delete state_machineExecuting a StepFunctionThestartsub-command can be used to start executing a StepFunction.$ heaviside start --json "{}" state_machineNote: By default thestartsub-command will wait until the
execution has finished and will print the output of the StepFunction.Python LibraryThe Heaviside package installs the Python libraryheaviside. There are three
components to the library.heaviside.compile: The method used to compile a Heaviside DSL file into
a AWS StepFunction.heaviside.StateMachine: Class for creating and executing StepFunctions.heaviside.activities: A submodule containing several helper classes providing
a framework for running StepFunction Activities.
See theActivities documentfor more information.CompatabilityCurrently Heaviside has only been tested with Python 2.7 and 3.5.Related Projectsstatelint: A Ruby project that verifies a AWS StepFunction definition file.
Includes checks like making sure that all states are reachable.
Helpful when developing a new StepFunction to ensure everything
is correct. It will catch structural problems that Heaviside
doesn't check for.LegalUse 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:Redistributions of source code or binary forms must adhere to the terms and conditions of any applicable software licenses.End-user documentation or notices, whether included as part of a redistribution or disseminated as part of a legal or scientific disclosure (e.g. publication) or advertisement, must include the following acknowledgement:  The Boss software system was designed and developed by the Johns Hopkins University Applied Physics Laboratory (JHU/APL).The names "The Boss", "JHU/APL", "Johns Hopkins University", "Applied Physics Laboratory", "MICrONS", or "IARPA" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contactBossAdmin@jhuapl.edu.This source code and library is distributed in the hope that it will be useful, but is provided without any warranty of any kind.