AWS Step Function State Language Builder (awssl)¶

The awssl package generates JSON that is compliant with the Amazon States Language (ASL), declaring State Machines for use in the AWS Step Function service:

import awssl

hello_world = awssl.Pass(
        Name="HelloWorld",
        ResultAsJSON={"Hello": "World!"},
        EndState=True)

sm = awssl.StateMachine(
        Comment="A Hello World example of the Amazon States Language using a Pass state",
        StartState=hello_world)

print sm

Which creates the following JSON:

{
    "Comment": "A Hello World example of the Amazon States Language using a Pass state",
    "StartAt": "HelloWorld",
    "States": {
        "HelloWorld": {
            "Comment": "",
            "End": true,
            "InputPath": "$",
            "OutputPath": "$",
            "Result": {
                "Hello": "World!"
            },
            "ResultPath": "$",
            "Type": "Pass"
        }
    },
    "Version": "1.0"
}

For more examples see the awssl git repo on github.

Catcher¶

The Catcher class defines how to continue processing when a failure occurs in a Task or Parallel execution.

For more details on Catcher, see the AWS documentation.

class awssl.Catcher(ErrorNameList=None, NextState=None)¶

Models a Catcher that can be used in a Task or Parallel state to catch errors and then redirect the StateMachine to another state to continue processing.

Parameters:	ErrorNameList (list of str) – [Required] The set of error names that this `Catcher` will handle. NextState (instance of class derived from `StateBase`) – [Required] Next state to be invoked within this branch.

clone(NameFormatString='{}')¶

Returns a clone of this instance.

If the next state invoked by this catcher is not an end state, then the next state will also be cloned, to establish a complete clone of the branch form this instance onwards.

Parameters:	NameFormatString (str) – [Required] The naming template to be applied to generate the name of next state in the new instance.
Returns:	`Catcher` – A new instance of this instance and any other instances in its branch.

get_error_name_list()¶

Returns the list of error names that this instance will handle.

Returns:	list of str – The list of error names

get_next_state()¶

Returns the StateBase instance that will be invoked if this Catcher traps an error

Returns:	`StateBase` – The next state to be invoked

set_error_name_list(ErrorNameList)¶

Sets the list of error names that this instance will handle.

ErrorNameList must not be None, and must be a non-empty list of str.

Parameters:	ErrorNameList (list of str) – [Required] The set of error names that this `Catcher` will handle.

set_next_state(NextState=None)¶

Sets the next state to be invoked if any of the specified error conditions occur. NextState must not be None.

Parameters:	NextState (instance of class derived from `StateBase`) – [Required] Next state to be invoked within this branch.

to_json()¶

Returns the JSON representation of this instance.

Returns:	dict – The JSON representation

validate()¶

Validates this instance is correctly specified.

Raises Exception with details of the error, if the instance is incorrectly defined.

Fail State¶

The Fail class acts as a end state of a state machine branch, signifying the state machine failed.

For more details on Fail, see the AWS documentation.

class awssl.Fail(Name='', Comment='', ErrorName='', ErrorCause='')¶

Models the Fail state, which terminates the state machine with an error code.

Parameters:	Name (str) – [Required] The name of the state within the branch of the state machine Comment (str) – [Optional] A comment describing the intent of this fail state ErrorName (str) – [Optional] A code to identify the error causing the failed state ErrorCause (str) – [Optional] More detailed information on the cause of the error

clone(NameFormatString='{}')¶

Returns a clone of this instance, with the clone named per the NameFormatString, to avoid state name clashes.

If this instance is not an end state, then the next state will also be cloned, to establish a complete clone of the branch form this instance onwards.

Parameters:	NameFormatString (str) – [Required] The naming template to be applied to generate the name of the new instance.
Returns:	`Fail` – A new instance of this instance and any other instances in its branch.

get_error_cause()¶

Returns the more detailed cause of the error that is associated with this instance.

Returns:	str – The cause of the error associated with this instance

get_error_name()¶

Returns the error name that is associated with this Fail instance

Returns:	str – The error name associated with this instance

set_error_cause(ErrorCause='')¶

Set the cause of the error associated with this instance.

Parameters:	ErrorCause (str) – [Optional] More detailed information on the cause of the error

set_error_name(ErrorName='')¶

Set the error name to be associated with this instance.

Parameters:	ErrorName (str) – [Optional] A code to identify the error causing the failed state.

to_json()¶

Returns the JSON representation of this instance.

Returns:	dict – The JSON representation

validate()¶

Validates this instance is correctly specified.

Raises Exception with details of the error, if the state machine is incorrectly defined.

Pass State¶

The Pass class acts as a pass through state, allowing new data to be added, or the input to be filtered.

For more details on Pass, see the AWS documentation.

class awssl.Pass(Name='', Comment='', InputPath='$', OutputPath='$', EndState=False, NextState=None, ResultPath='$', ResultAsJSON=None)¶

Models the Pass state, which can transfer input to output, or can inject specific values via set_result().

Either:

EndState is True and NextState must be None
EndState is False and NextState must be a valid instance of a class derived from StateBase.

Values can be returned by Pass by specifying a JSON result for ResultAsJSON such as:

{
        "output": "This is a value"
}

and then using OutputPath to filter, by specifing “$.output”.

Parameters:

Name (str) – [Required] The name of the state within the branch of the state machine
Comment (str) – [Optional] A comment describing the intent of this pass state
InputPath (str) – [Optional] Filter on the Input information to be passed to the Pass state. Default is “$”, signifying that all the Input information will be provided
OutputPath (str) – [Optional] Filter on the Output information to be returned from the Pass state. Default is “$”, signifying that all the result information will be provided
EndState (bool) – [Optional] Flag indicating if this state terminates a branch of the state machine. Defaults to False.
NextState (instance of class derived from StateBase) – [Optional] Next state to be invoked within this branch. Must not be None unless EndState is True.
ResultPath (dict) – [Optional] JSONPath indicating where results should be added to the Input. Defaults to “$”, indicating results replace the Input entirely.
ResultAsJSON – [Optional] Data to be returned by this state, in JSON format.

clone(NameFormatString='{}')¶

Returns a clone of this instance, with the clone named per the NameFormatString, to avoid state name clashes.

If this instance is not an end state, then the next state will also be cloned, to establish a complete clone of the branch form this instance onwards.

Parameters:	NameFormatString (str) – [Required] The naming template to be applied to generate the name of the new instance.
Returns:	`Pass` – A new instance of this instance and any other instances in its branch.

get_result()¶

Returns the JSON result of this instance.

Returns:	dict – The JSON representation

set_result(ResultAsJSON={})¶

Sets the result to be returned by this instance of Pass.

Parameters:	ResultAsJSON – [Optional] Data to be returned by this state, in JSON format.

to_json()¶

Returns the JSON representation of this instance.

Returns:	dict – The JSON representation

validate()¶

Validates this instance is correctly specified.

Raises Exception with details of the error, if the state machine is incorrectly defined.

Parallel State¶

The Parallel class allows concurrent processing, across arbitrary numbers of branches.

For more details on Parallel, see the AWS documentation.

class awssl.Parallel(Name=None, Comment='', InputPath='$', OutputPath='$', NextState=None, EndState=None, ResultPath='$', RetryList=None, CatcherList=None, BranchList=None)¶

Models the Parallel state.

Either:

EndState is True and NextState must be None
EndState is False and NextState must be a valid instance of a class derived from StateBase.

Output is returned as a list of the outputs from each branch.

Parameters:	Name (str) – [Required] The name of the state within the branch of the state machine Comment (str) – [Optional] A comment describing the intent of this pass state InputPath (str) – [Optional] Filter on the Input information to be passed to the Pass state. Default is “$”, signifying that all the Input information will be provided OutputPath (str) – [Optional] Filter on the Output information to be returned from the Pass state. Default is “$”, signifying that all the result information will be provided EndState (bool) – [Optional] Flag indicating if this state terminates a branch of the state machine. Defaults to `False` NextState (instance of class derived from `StateBase`) – [Optional] Next state to be invoked within this branch. Must not be `None` unless `EndState` is `True` ResultPath (str) – [Optional] JSONPath indicating where results should be added to the Input. Defaults to “$”, indicating results replace the Input entirely. RetryList – [Optional] `list` of `Retrier` instances corresponding to error states that cause the entire set of branches to be retried CatcherList – [Optional] `list` of `Catcher` instances corresponding to error states that can be caught and handled by further states being executed in the `StateMachine`. BranchList – [Required] `list` of `StateBase` instances, providing the starting states for each branch to be run concurrently
Type:	RetryList: list of `Retrier`
Type:	CatcherList: list of `Catcher`
Type:	BranchList: list of `StateBase`

add_branch(StartObject=None)¶: Adds a branch starting at the specified StartObject, which must be inherited from StateBase.

clone(NameFormatString='{}')¶

Returns a clone of this instance, with the clone named per the NameFormatString, to avoid state name clashes.

If this instance is not an end state, then the next state will also be cloned, to establish a complete clone of the branch form this instance onwards.

Parameters:	NameFormatString (str) – [Required] The naming template to be applied to generate the name of the new instance.
Returns:	`Parallel` – A new instance of this instance and any other instances in its branch.

set_branch_list(BranchList=None)¶

Sets the list of starting states for each branch to be executed concurrently.

At least one branch is required for the state to be valid.

Parameters:	BranchList – [Required] `list` of `StateBase` instances, providing the starting states for each branch to be run concurrently
Type:	BranchList: list of `StateBase`

to_json()¶

Returns the JSON representation of this instance.

Returns:	dict – The JSON representation

validate()¶

Validates this instance is correctly specified.

Raises Exception with details of the error, if the state is incorrectly defined.

Retrier¶

The Retrier class defines how to respond to a failure in a Task or Parallel execution.

For more details on Retrier, see the AWS documentation.

class awssl.Retrier(ErrorNameList=None, IntervalSeconds=1, MaxAttempts=3, BackoffRate=2.0)¶

Models a Retrier for a “Retry” field in a Task or Parallel state

Parameters:

ErrorNameList (list of str) – [Required] The set of error names that this Retrier will handle.
IntervalSeconds (int) – [Optional] The interval in seconds before retrying the state. Default is 1 second.
MaxAttempts (int) – [Optional] The maximum number of retry attempts. Default is 3.
BackoffRate (float) – [Optional] The growth rate in retry interval. Must be greater than 1.0. Default is 2.0.

clone()¶

Returns a clone of this instance.

Returns:	`Retrier` – A new instance of this instance and any other instances in its branch.

get_backoff_rate()¶

Returns the backoff rate that will be applied to the IntervalSeconds on each retry.

Returns:	float – The backoff rate for the `IntervalSeconds`.

get_error_name_list()¶

Returns the list of error names that this instance will handle.

Returns:	list of str – The list of error names

get_interval_seconds()¶

Returns the interval in seconds before the state machine will retry the associated failed state.

Returns:	int – The interval in seconds before retrying.

get_max_attempts()¶

Returns the maximum number of retry attempts of the associated failed state.

Returns:	int – The maximum number of retry attempts.

set_backoff_rate(BackoffRate=2.0)¶

Sets the backoff rate that will be applied to the IntervalSeconds after the first retry.

The backoff rate must be >= 1.0. Default is 2.0.

Parameters:	BackoffRate (float) – [Optional] The growth rate in retry interval.

set_error_name_list(ErrorNameList)¶

Sets the list of error names that this instance will handle.

ErrorNameList must not be None, and must be a non-empty list of str.

Parameters:	ErrorNameList (list of str) – [Required] The set of error names that this `Retrier` will handle.

set_interval_seconds(IntervalSeconds=1)¶

Sets the interval in seconds before the state machine will retry the associated failed state.

The interval must be >= 1 second. Default is 1 second.

Parameters:	IntervalSeconds (int) – [Optional] The interval in seconds before retrying the state.

set_max_attempts(MaxAttempts=3)¶

Sets the maximum number of retry attempts of the associated failed state.

The max attempts must be greater than or equal to zero. A value of zero indicates that no retry will be attempted. The default is 3.

Parameters:	MaxAttempts (int) – [Optional] The maximum number of retry attempts.

to_json()¶

Returns the JSON representation of this instance.

Returns:	dict – The JSON representation

validate()¶

Validates this instance is correctly specified.

Raises Exception with details of the error, if the state machine is incorrectly defined.

StateMachine¶

The StateMachine class builds the ASL compliant JSON, by walking the branch of states linked to the specified starting state.

For more details on StateMachine, see the AWS documentation.

class awssl.StateMachine(Comment='', ASLVersion='1.0', StartState=None)¶

StateMachine will execute the main branch, starting from the state specified by StartState.

The ASL JSON can be returned by calling print.

Parameters:	Comment (str) – [Optiona] A comment describing the processing of the state machine ASLVersion (str) – [Optional] The version of the ASL specification. Only 1.0 is currently supported StartState (any start class derived from `StateBase`) – [Required] The starting state for the start machine. Must not be `None`

get_asl_version()¶

Returns the ASL version specification used for the state machine definition.

Returns:	str – The version of ASL being used

get_comment()¶

Returns the comment describing the state machine.

Returns:	str – The comment associated with the state machine

get_start_state()¶

Returns the object representing the starting state for the state machine.

Returns:	`StateBase` – A state class derived from `StateBase`

set_asl_version(ASLVersion='1.0')¶

Sets the ASL version specification being used for the state machine definition.

Parameters:	ASLVersion (str) – [[Optional]] The version of the ASL specification. Only 1.0 is currently supported

set_comment(Comment='')¶

Sets the comment describing the state machine.

Parameters:	Comment (str) – [[Optional]] A description of the processing of the state machine

set_start_state(StartState=None)¶

Sets the starting state for the state machine.

Parameters:	StartState (any start class derived from `StateBase`) – [[Required]] The starting state for the start machine. Must not be `None`

validate()¶

Validates the state machine is correctly specified, compared to the version of the ASL being used.

Raises Exception with details of the error, if the state machine is incorrectly defined.

Succeed State¶

The Succeed class acts as a end state of a state machine branch, with the ability to provide filtered output data.

For more details on Succeed, see the AWS documentation.

class awssl.Succeed(Name='', Comment='', InputPath='$', OutputPath='$')¶

Succeed is a state that terminates a State Machine successfully.

Succeed are typically used as part of a Condition state, and can receive Input and return Output.

Parameters:

Name (str) – [Required] The name of the state within the branch of the state machine
Comment (str) – [Optional] A comment describing the intent of this pass state
InputPath (str) – [Optional] Filter on the Input information to be passed to the Pass state. Default is “$”, signifying that all the Input information will be provided
OutputPath (str) – [Optional] Filter on the Output information to be returned from the Pass state. Default is “$”, signifying that all the result information will be provided

clone(NameFormatString='{}')¶

Returns a clone of this instance, with the clone named per the NameFormatString, to avoid state name clashes.

If this instance is not an end state, then the next state will also be cloned, to establish a complete clone of the branch form this instance onwards.

Parameters:	NameFormatString (str) – [Required] The naming template to be applied to generate the name of the new instance.
Returns:	`Succeed` – A new instance of this instance and any other instances in its branch.

to_json()¶

Returns the JSON representation of this instance.

Returns:	dict – The JSON representation

validate()¶

Validates this instance is correctly specified.

Raises Exception with details of the error, if the state machine is incorrectly defined.

Task State¶

The Task class can invoke AWS Lambda functions or initiate Step Function Activities.

For more details on Task, see the AWS documentation.

class awssl.Task(Name=None, Comment='', InputPath='$', OutputPath='$', NextState=None, EndState=None, ResultPath='$', RetryList=None, CatcherList=None, ResourceArn=None, TimeoutSeconds=99999999, HeartbeatSeconds=99999999)¶

Models the Task state.

The Task can be used to invoke either an AWS Lambda function or an Activity, which provides a general mechanism for all types of processing. The Task supports retries and catching of specified errors to provide structured error handling, as well as supporting Timeout for processing as one of those error types.

Either:

EndState is True and NextState must be None
EndState is False and NextState must be a valid instance of a class derived from StateBase.

Parameters:	Name (str) – [Required] The name of the state within the branch of the state machine Comment (str) – [Optional] A comment describing the intent of this pass state InputPath (str) – [Optional] Filter on the Input information to be passed to the Pass state. Default is “$”, signifying that all the Input information will be provided OutputPath (str) – [Optional] Filter on the Output information to be returned from the Pass state. Default is “$”, signifying that all the result information will be provided EndState (bool) – [Optional] Flag indicating if this state terminates a branch of the state machine. Defaults to `False` NextState (instance of class derived from `StateBase`) – [Optional] Next state to be invoked within this branch. Must not be `None` unless `EndState` is `True` ResultPath (str) – [Optional] JSONPath indicating where results should be added to the Input. Defaults to “$”, indicating results replace the Input entirely. RetryList – [Optional] `list` of `Retrier` instances corresponding to error states that cause the entire set of branches to be retried CatcherList – [Optional] `list` of `Catcher` instances corresponding to error states that can be caught and handled by further states being executed in the `StateMachine`. ResourceArn – [Required] The Arn for the `Lambda` function or `Activity` that the `Task` should invoke
Type:	RetryList: list of `Retrier`
Type:	CatcherList: list of `Catcher`
Type:	ResourceArn: str
Param:	TimeoutSeconds: [Optional] The number of seconds in which the `Task` should complete
Type:	TimeoutSeconds: int
Param:	HeartbeatSeconds: [Optional] The number of seconds between heartbeats from an `Activity`, to indicate it is still running
Type:	HeartbeatSeconds: int

clone(NameFormatString='{}')¶

Returns a clone of this instance, with the clone named per the NameFormatString, to avoid state name clashes.

If this instance is not an end state, then the next state will also be cloned, to establish a complete clone of the branch form this instance onwards.

Parameters:	NameFormatString (str) – [Required] The naming template to be applied to generate the name of the new instance.
Returns:	`Task` – A new instance of this instance and any other instances in its branch.

get_heartbeat_seconds()¶

Returns the heartbeat interval for the Task. If more than two heartbeats are missed then the state will fail with a States.Timeout error.

Returns:	int – The heartbeat seconds for the state.

get_resource_arn()¶

Returns the Arn of the Lambda or Activity that will be invoked by this Task.

Returns:	str – The Arn of the resource to be invoked.

get_timeout_seconds()¶

Returns the timeout seconds for the Task, afterwhich a States.Timeout error is raised.

Returns:	int – The timeout seconds for the state.

set_heartbeat_seconds(HeartbeatSeconds=99999999)¶

Sets the heartbeats seconds for the Task. If more than two heartbeats are missed then the state will fail with a States.Timeout error.

If specified, must not be less than zero seconds. Default value is 99999999.

Param:	HeartbeatSeconds: [Optional] The number of seconds between heartbeats from an `Activity`, to indicate it is still running
Type:	HeartbeatSeconds: int

set_resource_arn(ResourceArn=None)¶

Sets the Arn of the Lambda of Activity to be invoked by this Task. Cannot be None and must be a valid Arn formatted string.

Parameters:	ResourceArn – [Required] The Arn for the `Lambda` function or `Activity` that the `Task` should invoke
Type:	ResourceArn: str

set_timeout_seconds(TimeoutSeconds=99999999)¶

Sets the timeout seconds for the Task, afterwhich a States.Timeout error is raised.

If specified, must not be less than zero seconds. Default value is 99999999.

Param:	TimeoutSeconds: [Optional] The number of seconds in which the `Task` should complete
Type:	TimeoutSeconds: int

to_json()¶

Returns the JSON representation of this instance.

Returns:	dict – The JSON representation

validate()¶

Validates this instance is correctly specified.

Raises Exception with details of the error, if the state is incorrectly defined.

Wait State¶

The Wait class pauses the branch the state is defined within, until the specified date/time or interval has passed.

For more details on Wait, see the AWS documentation.

class awssl.Wait(Name='', Comment='', InputPath='$', OutputPath='$', EndState=False, NextState=None, WaitForSeconds=None, WaitForSecondsPath=None, WaitUntilISO8601Timestamp=None, WaitUntilISO8601TimestampPath=None)¶

Wait is a Step Function state that pauses execution of the State Machine for a period of time.

Waits can be durations defined in seconds, or until a specific time. Waits can be non-declarative, and instead use values from the Input data to the state.

One (and only one) method of expressing the wait can be specified in each Wait state.

Either:

EndState is True and NextState must be None
EndState is False and NextState must be a valid instance of a class derived from StateBase.

Parameters:

Name (str) – [Required] The name of the state within the branch of the state machine
Comment (str) – [Optional] A comment describing the intent of this pass state
InputPath (str) – [Optional] Filter on the Input information to be passed to the Pass state. Default is “$”, signifying that all the Input information will be provided
OutputPath (str) – [Optional] Filter on the Output information to be returned from the Pass state. Default is “$”, signifying that all the result information will be provided
EndState (bool) – [Optional] Flag indicating if this state terminates a branch of the state machine. Defaults to False
NextState (instance of class derived from StateBase) – [Optional] Next state to be invoked within this branch. Must not be None unless EndState is True
WaitForSeconds (int) – [Optional] The number of seconds of the wait interval. If specified, this must be a positive integer.
WaitForSecondsPath (str) – [Optional] A JSONPath to a wait interval within the Input data provided to the state.
WaitUntilISO8601Timestamp (str) – [Optional] A datetime string that conforms to the RFC3339 profile of ISO 8601.
WaitUntilISO8601TimestampPath (str) – [Optional] A JSONPath to a datetime string that conforms to the RFC3339 profile of ISO 8601, within the Input data provided to the state.

clone(NameFormatString='{}')¶

Returns a clone of this instance, with the clone named per the NameFormatString, to avoid state name clashes.

If this instance is not an end state, then the next state will also be cloned, to establish a complete clone of the branch form this instance onwards.

Parameters:	NameFormatString (str) – [Required] The naming template to be applied to generate the name of the new instance.
Returns:	`Wait` – A new instance of this instance and any other instances in its branch.

get_wait_seconds()¶

Returns the wait interval in seconds.

Returns:	int – The wait interval

get_wait_seconds_path()¶

Returns the JSON Path with which to resolve the wait interval from the Input data supplied to the state.

Returns:	str

get_wait_timestamp()¶

Returns a timestamp as the RFC3339 profile of ISO 8601. The wait will stop its branch of the StateMachine until this time has passed

Returns:	str

get_wait_timestamp_path()¶

Returns the JSON Path with which to resolve the wait date/time from the Input data supplied to the state.

Returns:	str

set_wait_seconds(WaitForSeconds=1)¶

Sets the wait interval in seconds.

The interval must be a positive integer if specifed. Default value is 1 second.

Parameters:	WaitForSeconds (int) – [Optional] The number of seconds of the wait interval. If specified, this must be a positive integer.

set_wait_seconds_path(WaitForSecondsPath=None)¶

Sets the JSON Path with which to resolve the wait interval from the Input data supplied to the state.

Parameters:	WaitForSecondsPath (str) – [Optional] A JSONPath to a wait interval within the Input data provided to the state.

set_wait_timestamp(WaitUntilISO8601Timestamp)¶

Sets a date/time of the format RFC3339 profile of ISO 8601. The wait will stop its branch of the StateMachine until this time has passed

Parameters:	WaitUntilISO8601Timestamp (str) – [Optional] A datetime string that conforms to the RFC3339 profile of ISO 8601.

set_wait_timestamp_path(WaitUntilISO8601TimestampPath=None)¶

Sets a JSON Path of a date/time of the format RFC3339 profile of ISO 8601, which will be retrieved from the Input data passed to the state.

The wait will stop its branch of the StateMachine until this time has passed

Parameters:	WaitUntilISO8601TimestampPath – [Optional] A JSONPath to a datetime string that conforms to the RFC3339 profile of ISO 8601, within the Input data provided to the state.

to_json()¶

Returns the JSON representation of this instance.

Returns:	dict – The JSON representation

validate()¶

Validates this instance is correctly specified.

Raises Exception with details of the error, if the state is incorrectly defined.

Extension: BranchRetryParallel State¶

The BranchRetryParallel class extends the Parallel state.

Parallel supports retrying the state if one or more of its branches generates an error that is included in the Retrier list. This class extends this behaviour, allowing the branches to define errors that can be retried before the whole state is retried.

This extension can ensure that an intermittent failure on a single branch does not trigger significant unnecessary reprocessing of the successful branches.

For more details on Parallel, see the AWS documentation.

class awssl.ext.BranchRetryParallel(Name=None, Comment='', InputPath='$', OutputPath='$', NextState=None, EndState=None, ResultPath='$', RetryList=None, CatcherList=None, BranchList=None, BranchRetryList=None)¶

Extends the Parallel state, providing optional retries on each branch separately.

Either:

EndState is True and NextState must be None
EndState is False and NextState must be a valid instance of a class derived from StateBase.

Output is returned as a list of the outputs from each branch, as with Parallel.

Parameters:	Name (str) – [Required] The name of the state within the branch of the state machine Comment (str) – [Optional] A comment describing the intent of this pass state InputPath (str) – [Optional] Filter on the Input information to be passed to the Pass state. Default is “$”, signifying that all the Input information will be provided OutputPath (str) – [Optional] Filter on the Output information to be returned from the Pass state. Default is “$”, signifying that all the result information will be provided EndState (bool) – [Optional] Flag indicating if this state terminates a branch of the state machine. Defaults to `False` NextState (instance of class derived from `StateBase`) – [Optional] Next state to be invoked within this branch. Must not be `None` unless `EndState` is `True` ResultPath (str) – [Optional] JSONPath indicating where results should be added to the Input. Defaults to “$”, indicating results replace the Input entirely. RetryList – [Optional] `list` of `Retrier` instances corresponding to error states that cause the entire set of branches to be retried CatcherList – [Optional] `list` of `Catcher` instances corresponding to error states that can be caught and handled by further states being executed in the `StateMachine`. BranchList – [Required] `list` of `StateBase` instances, providing the starting states for each branch to be run concurrently BranchRetryList – [Optional] `list` of `Retrier` instances corresponding to error states that can be retried for each branch
Type:	RetryList: list of `Retrier`
Type:	CatcherList: list of `Catcher`
Type:	BranchList: list of `StateBase`
Type:	BranchRetryList: list of `StateBase`

clone(NameFormatString='{}')¶

Returns a clone of this instance, with the clone named per the NameFormatString, to avoid state name clashes.

If this instance is not an end state, then the next state will also be cloned, to establish a complete clone of the branch form this instance onwards.

Parameters:	NameFormatString (str) – [Required] The naming template to be applied to generate the name of the new instance.
Returns:	`BranchRetryParallel` – A new instance of this instance and any other instances in its branch.

get_branch_list()¶

Returns the list of starting states for each branch to be executed concurrently

Returns:	`list` of `StateBase` instances

get_branch_retry_list()¶

Returns the list of Retrier instances that will be applied to each branch separately, allowing failure in one branch to be retried without having to re-execute all the branches of the Parallel.

Returns:	`list` of `Retrier` instances

set_branch_list(BranchList=None)¶

Sets the list of starting states for each branch to be executed concurrently.

At least one branch is required for the state to be valid.

Parameters:	BranchList – [Required] `list` of `StateBase` instances, providing the starting states for each branch to be run concurrently
Type:	BranchList: list of `StateBase`

set_branch_retry_list(BranchRetryList=None)¶

Sets the list of Retrier instance to be applied to the branches in the Parallel.

If none are set, then the behaviour of this state is equivalent to the Parallel state.

Parameters:	BranchRetryList – [Optional] `list` of `Retrier` instances corresponding to error states that can be retried for each branch
Type:	BranchRetryList: list of `StateBase`

to_json()¶

Returns the JSON representation of this instance.

Returns:	dict – The JSON representation

validate()¶

Validates this instance is correctly specified.

Raises Exception with details of the error, if the state machine is incorrectly defined.

Extension: For State¶

The For state provides a “for” loop, from a starting value to an ending value, incrementing via a defined step.

The For state allows a single branch to be executed multiple times, either sequentially or concurrently. Each execution is supplied the value of the iterator, at a location that can be specified by the IteratorPath argument.

One use case for this class occurs where processing will exceed the maximum execution time for an AWS Lambda (currently 300 seconds), but can be efficiently partitioned. The For state then allows processing to be handled in AWS Lambda rather than having to create and maintain an Activity.

class awssl.ext.For(Name=None, Comment='', InputPath='$', OutputPath='$', NextState=None, EndState=None, ResultPath='$', RetryList=None, CatcherList=None, BranchState=None, From=0, To=0, Step=1, IteratorPath='$.iteration', ParallelIteration=False)¶

Models the For extension state.

The For state constructs and executes branches for each iterator value in the range [From, To), incrementing by Step.

The same branch is repeatedly executed, with the iterator value injected into the Input data at the location specified by IteratorPath.

The state supports both retry and catch, so that errors can be handled at the state level. If retries are specified, then all the iterations will be re-executed.

Either:

EndState is True and NextState must be None
EndState is False and NextState must be a valid instance of a class derived from StateBase.

Parameters:	Name (str) – [Required] The name of the state within the branch of the state machine Comment (str) – [Optional] A comment describing the intent of this pass state InputPath (str) – [Optional] Filter on the Input information to be passed to the Pass state. Default is “$”, signifying that all the Input information will be provided OutputPath (str) – [Optional] Filter on the Output information to be returned from the Pass state. Default is “$”, signifying that all the result information will be provided EndState (bool) – [Optional] Flag indicating if this state terminates a branch of the state machine. Defaults to `False` NextState (instance of class derived from `StateBase`) – [Optional] Next state to be invoked within this branch. Must not be `None` unless `EndState` is `True` ResultPath (str) – [Optional] JSONPath indicating where results should be added to the Input. Defaults to “$”, indicating results replace the Input entirely. RetryList – [Optional] `list` of `Retrier` instances corresponding to error states that cause the entire set of branches to be retried CatcherList – [Optional] `list` of `Catcher` instances corresponding to error states that can be caught and handled by further states being executed in the `StateMachine`. BranchState (`StateBase`) – [Required] The starting `StateBase` instance of the branch to be executed on each iteration of the `For` loop From (int or float) – [Required] The starting value of the iteration. Must be an integer or float To (int or float) – [Required] The ending value of the iteration. Must be an integer or float Step – [Required] The incremental value of each iteration. Must be an integer or float, and cannot be zero. Default is 1. IteratorPath (str) – [Required] The JSONPath specifying the injection location for the iterator value into the Input data ParallelIteration (bool) – [Optional] Whether the `For` branches can be run concurrently or must be executed sequentially. Default is sequential.
Type:	RetryList: list of `Retrier`
Type:	CatcherList: list of `Catcher`

clone(NameFormatString='{}')¶

Returns a clone of this instance, with the clone named per the NameFormatString, to avoid state name clashes.

If this instance is not an end state, then the next state will also be cloned, to establish a complete clone of the branch form this instance onwards.

Parameters:	NameFormatString (str) – [Required] The naming template to be applied to generate the name of the new instance.
Returns:	`For` – A new instance of this instance and any other instances in its branch.

get_branch_state()¶

Returns the starting state of the branch to be executed within the For loop.

Returns:	`StateBase`

get_from()¶

Returns the starting value for the For loop

Returns:	int or float

get_iterator_path()¶

Returns the JSON Path of the injection location, into which the loop iterator value will be added, as the Input data is passed to the branch.

Returns:	str

get_parallel_iteration()¶

Returns whether the For loop will execute concurrently or sequentially.

Returns:	bool

get_step()¶

Returns the increment value for the For loop

Returns:	int or float

get_to()¶

Returns the ending value for the For loop

Returns:	int or float

set_branch_state(BranchState=None)¶

Sets the starting state of the branch to be executed within the For loop.

Parameters:	BranchState (`StateBase`) – [Required] The starting `StateBase` instance of the branch to be executed on each iteration of the `For` loop

set_from(From=0)¶

Sets the starting value for the For loop. Must be an integer or float. Default value is zero.

Parameters:	From (int or float) – [Required] The starting value of the iteration.

set_iterator_path(IteratorPath='$.iteration')¶

Sets the JSON Path of the injection location, into which the loop iterator value will be added, as the Input data is passed to the branch.

Parameters:	IteratorPath (str) – [Required] The JSONPath specifying the injection location for the iterator value into the Input data

set_parallel_iteration(ParallelIteration=False)¶

Specifies whether the execution of the For loop can be performed concurrently, or must be sequential. Default is sequential.

Parameters:	ParallelIteration (bool) – [Optional] Whether the `For` branches can be run concurrently or must be executed sequentially.

set_step(Step=1)¶

Sets the increment value for the For loop. Must be an integer or float. Default value is 1.

Parameters:	Step (int or float) – [Required] The increment value of the iteration.

set_to(To=0)¶

Sets the ending value for the For loop. Must be an integer or float. Default value is zero.

Parameters:	To (int or float) – [Required] The ending value of the iteration.

to_json()¶

Returns the JSON representation of this instance.

Returns:	dict – The JSON representation

validate()¶

Validates this instance is correctly specified.

Raises Exception with details of the error, if the state is incorrectly defined.

Extension: LimitedParallel State¶

The LimitedParallel class allows concurrent processing, across arbitrary invocations of the same branch, but limited by a maximum number of concurrent executions.

This allows finer control over AWS Lambda invocations to avoid unexpected throttling by AWS Lambda (and associated timeouts, due to exceeding the maximum number of Lambda concurrent executions per second.

For more details on Parallel, see the AWS documentation.

class awssl.ext.LimitedParallel(Name=None, Comment='', InputPath='$', OutputPath='$', NextState=None, EndState=None, ResultPath='$', RetryList=None, CatcherList=None, BranchState=None, Iterations=0, MaxConcurrency=1, IteratorPath='$.iteration')¶

Limited Parallel allows a throttled amount of concurrent processing, constrained by the value of MaxConcurrent.

Each branch executed is the same, starting at BranchState, and the number of branch executions is specified by Iterations.

The value of the iterator is passed to each branch, so that Task``s in the branch can process appropriately. The location of the iterator is specified by ``IteratorPath.

Either:

EndState is True and NextState must be None
EndState is False and NextState must be a valid instance of a class derived from StateBase.

Output is returned as a list of the outputs from each branch.

Parameters:	Name (str) – [Required] The name of the state within the branch of the state machine Comment (str) – [Optional] A comment describing the intent of this pass state InputPath (str) – [Optional] Filter on the Input information to be passed to the Pass state. Default is “$”, signifying that all the Input information will be provided OutputPath (str) – [Optional] Filter on the Output information to be returned from the Pass state. Default is “$”, signifying that all the result information will be provided EndState (bool) – [Optional] Flag indicating if this state terminates a branch of the state machine. Defaults to `False` NextState (instance of class derived from `StateBase`) – [Optional] Next state to be invoked within this branch. Must not be `None` unless `EndState` is `True` ResultPath (str) – [Optional] JSONPath indicating where results should be added to the Input. Defaults to “$”, indicating results replace the Input entirely. RetryList – [Optional] `list` of `Retrier` instances corresponding to error states that cause the entire set of branches to be retried CatcherList – [Optional] `list` of `Catcher` instances corresponding to error states that can be caught and handled by further states being executed in the `StateMachine`. BranchState – [Required] `StateBase` instance, providing the starting state for each branch to be run concurrently
Type:	RetryList: list of `Retrier`
Type:	CatcherList: list of `Catcher`
Type:	BranchState: `StateBase`
Param:	Iterations: [Required] The total number of branches to be executed. Must be larger than zero
Type:	Iterations: int
Param:	MaxConcurrency: [Required] The maximum number of branches that are to executed concurrently. Must be larger than zero
Type:	MaxConcurrency: int
Param:	IteratorPath: [Required] The JSONPath in which to inject the iterator value into the Input passed to the branch
Type:	IteratorPath: str

clone(NameFormatString='{}')¶

Returns a clone of this instance, with the clone named per the NameFormatString, to avoid state name clashes.

If this instance is not an end state, then the next state will also be cloned, to establish a complete clone of the branch form this instance onwards.

Parameters:	NameFormatString (str) – [Required] The naming template to be applied to generate the name of the new instance.
Returns:	`LimitedParallel` – A new instance of this instance and any other instances in its branch.

get_branch_state()¶

Returns the initial state for the branch processing

Returns:	`StateBase` – The initial state of the branch

get_iterations()¶

Returns the total number of branch executions to be performed

Returns:	int – The total number of branch executions to perform

get_iterator_path()¶

Returns the injection JSONPath to be used to add the iterator value into the Input for a branch

Returns:	str – The JSONPath for iterator value injection

get_max_concurrency()¶

Returns the maxiumum number of concurrent branch executions

Returns:	`int` – The maximum number of concurrent branch executions

set_branch_state(BranchState=None)¶

Set the initial state for the branch processing

Parameters:	BranchState – [Required] `StateBase` instance, providing the starting state for each branch to be run concurrently
Type:	BranchState: `StateBase`

set_iterations(Iterations=0)¶

Sets the total number of branch executions to be performed. Must be larger than zero.

Param:	Iterations: [Required] The total number of branches to be executed. Must be larger than zero
Type:	Iterations: int

set_iterator_path(IteratorPath='$.iteration')¶

Sets the injection JSONPath to use to add the iterator value into the Input for a branch

Param:	IteratorPath: [Required] The JSONPath in which to inject the iterator value into the Input passed to the branch
Type:	IteratorPath: str

set_max_concurrency(MaxConcurrency=1)¶

Sets the maximum number of concurrent branch executions, and the supplied value must be greater than zero. Default is sequential processing.

Param:	MaxConcurrency: [Required] The maximum number of branches that are to executed concurrently. Must be larger than zero
Type:	MaxConcurrency: int

to_json()¶

Returns the JSON representation of this instance.

Returns:	dict – The JSON representation

validate()¶

Validates this instance is correctly specified.

Raises Exception with details of the error, if the state is incorrectly defined.

Initialisation of Ext State Types¶

The For and LimitedParallel extension states require data manipulation between states, and this is supported by a series of Lambda functions.

The Lambda function themselves can be found in the github repo, and they have been incorporated into an AWS CloudFormation script so that they can be easily added to the AWS account / region that the AWS Step Function state machines will be executed.

Once created, the Arns of the Lambda functions must be passed to the awssl package; this is the purpose of these functions.

awssl.ext.get_ext_arn(key)¶

Returns the value of the Arn associated with the specified key.

Parameters:	key (str) – The key of the Lambda function whose Arn is required
Returns:	str

awssl.ext.get_ext_arn_keys()¶

Returns the list of keys against which Arns are defined.

Returns:	list

awssl.ext.set_ext_arns(ForInitializer=None, ForExtractor=None, ForConsolidator=None, ForFinalizer=None, ForFinalizerParallelIterations=None, LimitedParallelConsolidator=None)¶

Initialises the awssl.ext package, so that the correct Lambda functions are used in the ext states.

The functions are available in the github repo both as individual lambdas or combined in a CloudFormation script for easy deployment.

All the Arns must be specified or this function will generate an Exception.

Parameters:

ForInitializer (str) – The Arn of the ForInitializer Lambda function, used by the For state
ForExtractor (str) – The Arn of the ForExtractor Lambda function, used by the For state
ForConsolidator (str) – The Arn of the ForConsolidator Lambda function, used by the For state
ForFinalizer (str) – The Arn of the ForFinalizer Lambda function, used by the For state
ForFinalizerParallelIterations (str) – The Arn of the ForFinalizerParallelIterations Lambda function, used by the For state
LimitedParallelConsolidator (str) – The Arn of the LimitedParallelConsolidator Lambda function, used by the LimitedParallel state

AWS Step Function State Language Builder (awssl)¶

Catcher¶

Fail State¶

Pass State¶

Parallel State¶

Retrier¶

StateMachine¶

Succeed State¶

Task State¶

Wait State¶

Extension: BranchRetryParallel State¶

Extension: For State¶

Extension: LimitedParallel State¶

Initialisation of Ext State Types¶

Indices and tables¶