States

This module implements elements of the Amazon States Language.

class stepfunctions.steps.states.Block(**kwargs)

Bases: object

Base class to abstract blocks used in Amazon States Language.

to_json(pretty=False)

Serialize to a JSON formatted string.

Parameters:pretty (bool, optional) – Boolean flag set to True if JSON string should be prettified. False, otherwise. (default: False)
Returns:JSON formatted string representation of the block.
Return type:str
class stepfunctions.steps.states.State(state_id, state_type, output_schema=None, **kwargs)

Bases: stepfunctions.steps.states.Block

Base class to abstract states in Amazon States Language.

Parameters:
  • state_id (str) – State name whose length must be less than or equal to 128 unicode characters. State names must be unique within the scope of the whole state machine.
  • state_type (str) – Type of the state. (Allowed values: ‘Pass’, ‘Succeed’, ‘Fail’, ‘Wait’, ‘Task’, ‘Choice’, ‘Parallel’, ‘Map’).
  • output_schema (dict) – Expected output schema for the State. This is used to validate placeholder inputs used by the next state in the state machine. (default: None)
  • comment (str, optional) – Human-readable comment or description. (default: None)
  • input_path (str, optional) – Path applied to the state’s raw input to select some or all of it; that selection is used by the state. (default: ‘$’)
  • parameters (dict, optional) – The value of this field becomes the effective input for the state.
  • result_path (str, optional) – Path specifying the raw input’s combination with or replacement by the state’s result. (default: ‘$’)
  • output_path (str, optional) – Path applied to the state’s output after the application of result_path, producing the effective output which serves as the raw input for the next state. (default: ‘$’)
update_parameters(params)

Update parameters field in the state, if supported.

Parameters:params (dict or list) – The value of this field becomes the effective input for the state.
next(next_step)

Specify the next state or chain to transition to.

Parameters:next_step (State or Chain) – Next state or chain to transition to.
Returns:Next state or chain that will be transitioned to.
Return type:State or Chain
output()

Get the placeholder collection for the State’s output.

Returns:Placeholder collection representing the State’s output, and consequently the input to the next state in the workflow (if one exists).
Return type:StepInput
add_retry(retry)

Add a Retry block to the tail end of the list of retriers for the state.

Parameters:retry (Retry) – Retry block to add.
add_catch(catch)

Add a Catch block to the tail end of the list of catchers for the state.

Parameters:catch (Catch) – Catch block to add.
class stepfunctions.steps.states.Chain(steps=[])

Bases: object

Chain is a logical group of states, that resembles a linked list. The start state is the head of the Chain and the end state is the tail of the Chain.

Parameters:steps (list(State), optional) – List of states to be chained in-order. (default: [])
append(step)

Add a state at the tail end of the chain.

Parameters:step (State) – State to insert at the tail end of the chain.
class stepfunctions.steps.states.Pass(state_id, **kwargs)

Bases: stepfunctions.steps.states.State

Pass State simply passes its input to its output, performing no work. Pass States are useful when constructing and debugging state machines.

Parameters:
  • state_id (str) – State name whose length must be less than or equal to 128 unicode characters. State names must be unique within the scope of the whole state machine.
  • comment (str, optional) – Human-readable comment or description. (default: None)
  • input_path (str, optional) – Path applied to the state’s raw input to select some or all of it; that selection is used by the state. (default: ‘$’)
  • parameters (dict, optional) – The value of this field becomes the effective input for the state.
  • result_path (str, optional) – Path specifying the raw input’s combination with or replacement by the state’s result. (default: ‘$’)
  • result (str, optional) – If present, its value is treated as the output of a virtual task, and placed as prescribed by the result_path field, if any, to be passed on to the next state. If result is not provided, the output is the input.
  • output_path (str, optional) – Path applied to the state’s output after the application of result_path, producing the effective output which serves as the raw input for the next state. (default: ‘$’)
class stepfunctions.steps.states.Succeed(state_id, **kwargs)

Bases: stepfunctions.steps.states.State

Succeed State terminates a state machine successfully. The Succeed State is a useful target for Choice-state branches that don’t do anything but terminate the machine.

Parameters:
  • state_id (str) – State name whose length must be less than or equal to 128 unicode characters. State names must be unique within the scope of the whole state machine.
  • comment (str, optional) – Human-readable comment or description. (default: None)
  • input_path (str, optional) – Path applied to the state’s raw input to select some or all of it; that selection is used by the state. (default: ‘$’)
  • output_path (str, optional) – Path applied to the state’s output, producing the effective output which serves as the raw input for the next state. (default: ‘$’)
class stepfunctions.steps.states.Fail(state_id, **kwargs)

Bases: stepfunctions.steps.states.State

Fail State terminates the machine and marks it as a failure.

Parameters:
  • state_id (str) – State name whose length must be less than or equal to 128 unicode characters. State names must be unique within the scope of the whole state machine.
  • error (str) – Error name that can be used for error handling (retry/catch), operational, or diagnostic purposes.
  • cause (str) – Human-readable message describing the cause of the failure/error.
  • comment (str, optional) – Human-readable comment or description. (default: None).
class stepfunctions.steps.states.Wait(state_id, **kwargs)

Bases: stepfunctions.steps.states.State

Wait state causes the interpreter to delay the machine from continuing for a specified time. The time can be specified as a wait duration, specified in seconds, or an absolute expiry time, specified as an ISO-8601 extended offset date-time format string.

The Wait state must contain exactly one of seconds, seconds_path, timestamp, or timestamp_path.

Parameters:
  • state_id (str) – State name whose length must be less than or equal to 128 unicode characters. State names must be unique within the scope of the whole state machine.
  • seconds (int) – Wait duration specified in seconds.
  • seconds_path (str) – Path applied to the state’s input to select the wait duration in seconds.
  • timestamp (str) – Absolute expiry time, specified as an ISO-8601 extended offset date-time format string.
  • timestamp_path (str) – Path applied to the state’s input to select the timestamp to be used for wait duration.
  • comment (str, optional) – Human-readable comment or description. (default: None)
  • input_path (str, optional) – Path applied to the state’s raw input to select some or all of it; that selection is used by the state. (default: ‘$’)
  • output_path (str, optional) – Path applied to the state’s output, producing the effective output which serves as the raw input for the next state. (default: ‘$’)
class stepfunctions.steps.states.Task(state_id, **kwargs)

Bases: stepfunctions.steps.states.State

Task State causes the interpreter to execute the work identified by the state’s resource field.

Parameters:
  • state_id (str) – State name whose length must be less than or equal to 128 unicode characters. State names must be unique within the scope of the whole state machine.
  • resource (str) – A URI that uniquely identifies the specific task to execute. The States language does not constrain the URI scheme nor any other part of the URI.
  • timeout_seconds (int, optional) – Positive integer specifying timeout for the state in seconds. If the state runs longer than the specified timeout, then the interpreter fails the state with a States.Timeout Error Name. (default: 60)
  • heartbeat_seconds (int, optional) – Positive integer specifying heartbeat timeout for the state in seconds. This value should be lower than the one specified for timeout_seconds. If more time than the specified heartbeat elapses between heartbeats from the task, then the interpreter fails the state with a States.Timeout Error Name.
  • comment (str, optional) – Human-readable comment or description. (default: None)
  • input_path (str, optional) – Path applied to the state’s raw input to select some or all of it; that selection is used by the state. (default: ‘$’)
  • parameters (dict, optional) – The value of this field becomes the effective input for the state.
  • result_path (str, optional) – Path specifying the raw input’s combination with or replacement by the state’s result. (default: ‘$’)
  • output_path (str, optional) – Path applied to the state’s output after the application of result_path, producing the effective output which serves as the raw input for the next state. (default: ‘$’)
class stepfunctions.steps.states.Choice(state_id, **kwargs)

Bases: stepfunctions.steps.states.State

Choice state adds branching logic to a state machine. The state holds a list of rule and next_step pairs. The interpreter attempts pattern-matches against the rules in list order and transitions to the state or chain specified in the next_step field on the first rule where there is an exact match between the input value and a member of the comparison-operator array.

Parameters:
  • state_id (str) – State name whose length must be less than or equal to 128 unicode characters. State names must be unique within the scope of the whole state machine.
  • comment (str, optional) – Human-readable comment or description. (default: None)
  • input_path (str, optional) – Path applied to the state’s raw input to select some or all of it; that selection is used by the state. (default: ‘$’)
  • output_path (str, optional) – Path applied to the state’s output, producing the effective output which serves as the raw input for the next state. (default: ‘$’)
add_choice(rule, next_step)

Add a rule, next_step pair to the choice state.

Parameters:
default_choice(next_step)

Add a default step to the choice state.

The default step executes if none of the specified rules match.

Parameters:next_step (State or Chain) – Next state or chain to transition to, if none of the specified rules match.
class stepfunctions.steps.states.Parallel(state_id, **kwargs)

Bases: stepfunctions.steps.states.State

Parallel State causes parallel execution of “branches”.

A Parallel state causes the interpreter to execute each branch as concurrently as possible, and wait until each branch terminates (reaches a terminal state) before processing the next state in the Chain.

Parameters:
  • state_id (str) – State name whose length must be less than or equal to 128 unicode characters. State names must be unique within the scope of the whole state machine.
  • comment (str, optional) – Human-readable comment or description. (default: None)
  • input_path (str, optional) – Path applied to the state’s raw input to select some or all of it; that selection is used by the state. (default: ‘$’)
  • parameters (dict, optional) – The value of this field becomes the effective input for the state.
  • result_path (str, optional) – Path specifying the raw input’s combination with or replacement by the state’s result. (default: ‘$’)
  • output_path (str, optional) – Path applied to the state’s output after the application of result_path, producing the effective output which serves as the raw input for the next state. (default: ‘$’)
add_branch(branch)

Add a State or Chain as a branch to the Parallel state.

Parameters:branch (State or Chain) – State or Chain to attach as a branch to the Parallel state.
class stepfunctions.steps.states.Map(state_id, **kwargs)

Bases: stepfunctions.steps.states.State

Map state provides the ability to dynamically iterate over a state/subgraph for each entry in a list.

A Map state can accept an input with a list of items, execute a state or chain for each item in the list, and return a list, with all corresponding results of each execution, as its output.

Parameters:
  • state_id (str) – State name whose length must be less than or equal to 128 unicode characters. State names must be unique within the scope of the whole state machine.
  • iterator (State or Chain) – State or chain to execute for each of the items in items_path.
  • items_path (str, optional) – Path in the input for items to iterate over. (default: ‘$’)
  • max_concurrency (int, optional) – Maximum number of iterations to have running at any given point in time. (default: 0)
  • comment (str, optional) – Human-readable comment or description. (default: None)
  • input_path (str, optional) – Path applied to the state’s raw input to select some or all of it; that selection is used by the state. (default: ‘$’)
  • parameters (dict, optional) – The value of this field becomes the effective input for the state.
  • result_path (str, optional) – Path specifying the raw input’s combination with or replacement by the state’s result. (default: ‘$’)
  • result_path – Path specifying the raw input’s combination with or replacement by the state’s result. (default: ‘$’)
  • output_path (str, optional) – Path applied to the state’s output after the application of result_path, producing the effective output which serves as the raw input for the next state. (default: ‘$’)
attach_iterator(iterator)

Attach State or Chain as iterator to the Map state, that will execute for each of the items in items_path. If an iterator was attached previously with the Map state, it will be replaced.

Parameters:iterator (State or Chain) – State or Chain to attach as iterator to the Map state.
class stepfunctions.steps.states.Retry(**kwargs)

Bases: stepfunctions.steps.states.Block

A class for creating a Retry block.

Initialize a Retry block.

Parameters:
  • error_equals (list(str)) – Non-empty list of strings, which match Error Names. When a state reports an error, the interpreter scans through the retriers and, when the Error Name appears in the value of of a retrier’s error_equals field, implements the retry policy described in that retrier.
  • interval_seconds (int, optional) – Positive integer representing the number of seconds before the first retry attempt. (default: 1)
  • max_attempts (int, optional) – Non-negative integer representing the maximum number of retry attempts. (default: 3)
  • backoff_rate (float, optional) – A number which is the multiplier that increases the retry interval on each attempt. (default: 2.0)
class stepfunctions.steps.states.Catch(next_step, **kwargs)

Bases: stepfunctions.steps.states.Block

A class for creating a Catch block.

Initialize a Catch block.

Parameters:
  • error_equals (list(str)) –

    Non-empty list of strings, which match Error Names. When a state reports an error, the interpreter scans through the catchers and, when the Error Name appears in the value of of a catcher’s error_equals field, transitions to the next_step described in the catcher.

  • next_step (State or Chain) – Next state or chain to transition to.