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.
-
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
-
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: [])
-
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)
- timeout_seconds_path (str, optional) – Path specifying the state’s timeout value in seconds from the state input. When resolved, the path must select a field whose value is a positive integer.
- 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.
- heartbeat_seconds_path (str, optional) – Path specifying the state’s heartbeat value in seconds from the state input. When resolved, the path must select a field whose value is a positive integer.
- 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: - rule (
stepfunctions.steps.choice_rule.BaseRule
) – Rule to pattern match the input against. - next_step (State or Chain) – Next state or chain to transition to, if rule is matches with the input.
- rule (
-
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: ‘$’)
-
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: ‘$’)
- 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.
- error_equals (list(str)) –