runway.cfngin.plan module¶
CFNgin plan, plan componenets, and functions for interacting with a plan.
-
runway.cfngin.plan.
json_serial
(obj)[source]¶ Serialize json.
- Parameters
obj (Any) – A python object.
Example
json.dumps(data, default=json_serial)
-
runway.cfngin.plan.
merge_graphs
(graph1, graph2)[source]¶ Combine two Graphs into one, retaining steps.
-
class
runway.cfngin.plan.
Step
(stack, fn=None, watch_func=None)[source]¶ Bases:
object
State machine for executing generic actions related to stacks.
-
fn
¶ Function to run to execute the step. This function will be ran multiple times until the step is “done”.
- Type
Optional[Callable]
-
logger
¶ Logger for logging messages about the step.
- Type
logging.LoggerAdaptor
-
stack
¶ the stack associated with this step
-
status
¶ The status of step.
-
watch_func
¶ Function that will be called to “tail” the step action.
- Type
Optional[Callable]
Instantiate class.
- Parameters
stack (
runway.cfngin.stack.Stack
) – The stack associated with this stepfn (Optional[Callable]) – Function to run to execute the step. This function will be ran multiple times until the step is “done”.
watch_func (Optional[Callable]) – Function that will be called to “tail” the step action.
-
property
name
¶ Name of the step.
This is equal to the name of the stack it operates on.
- Returns
str
-
property
requires
¶ Return a list of step names this step depends on.
- Returns
List[str]
-
property
required_by
¶ Return a list of step names that depend on this step.
- Returns
List[str]
-
property
completed
¶ Return True if the step is in a COMPLETE state.
- Returns
bool
-
property
skipped
¶ Return True if the step is in a SKIPPED state.
- Returns
bool
-
property
failed
¶ Return True if the step is in a FAILED state.
- Returns
bool
-
property
done
¶ Return True if the step is finished.
To be
True
, status must be either COMPLETE, SKIPPED or FAILED)- Returns
bool
-
property
ok
¶ Return True if the step is finished (either COMPLETE or SKIPPED).
- Returns
bool
-
property
submitted
¶ Return True if the step is SUBMITTED, COMPLETE, or SKIPPED.
- Returns
bool
-
set_status
(status)[source]¶ Set the current step’s status.
- Parameters
status (
runway.cfngin.status.Status
) – The status to set the step to.
-
classmethod
from_stack_name
(stack_name, context, requires=None, fn=None, watch_func=None)[source]¶ Create a step using only a stack name.
- Parameters
stack_name (str) – Name of a CloudFormation stack.
context (
runway.cfngin.context.Context
) – Context object. Required to initialize a “fake”runway.cfngin.stack.Stack
.requires (List[str]) – Stacks that this stack depends on.
fn (Callable) – The function to run to execute the step. This function will be ran multiple times until the step is “done”.
watch_func (Callable) – an optional function that will be called to “tail” the step action.
- Returns
-
classmethod
from_persistent_graph
(graph_dict, context, fn=None, watch_func=None)[source]¶ Create a steps for a persistent graph dict.
- Parameters
context (
runway.cfngin.context.Context
) – Context object. Required to initialize a “fake”runway.cfngin.stack.Stack
.requires (List[str]) – Stacks that this stack depends on.
fn (Callable) – The function to run to execute the step. This function will be ran multiple times until the step is “done”.
watch_func (Callable) – an optional function that will be called to “tail” the step action.
- Returns
List[
Step
]
-
-
class
runway.cfngin.plan.
Graph
(steps=None, dag=None)[source]¶ Bases:
object
Graph represents a graph of steps.
The
Graph
helps organize the steps needed to execute a particular action for a set ofrunway.cfngin.stack.Stack
objects. When initialized with a set of steps, it will first build a Directed Acyclic Graph from the steps and their dependencies.-
dag
¶ an optional
runway.cfngin.dag.DAG
object. If one is not provided, a new one will be initialized.
Example:
>>> dag = DAG() >>> a = Step("a", fn=build) >>> b = Step("b", fn=build) >>> dag.add_step(a) >>> dag.add_step(b) >>> dag.connect(a, b)
Instantiate class.
- Parameters
steps (Optional[Dict[str,
Step
]]) – Dict with key of step name and value ofStep
for steps to initialize the Graph with. Note that if this is provided, a pre-configuredrunway.cfngin.dag.DAG
that already includes these steps should also be provided..dag (Optional[
runway.cfngin.dag.DAG
]) – An optionalrunway.cfngin.dag.DAG
object. If one is not provided, a new one will be initialized.
-
add_step_if_not_exists
(step, add_dependencies=False, add_dependants=False)[source]¶ Try to add a step to the graph.
Can be used when failure to add is acceptable.
-
add_steps
(steps)[source]¶ Add a list of steps.
- Parameters
steps (List[
Step
]) – The step to be added.
-
pop
(step, default=None)[source]¶ Remove a step from the graph.
- Parameters
step (
Step
) – The step to remove from the graph.default (Any) – Returned if the step could not be popped
- Returns
Any
-
transitive_reduction
()[source]¶ Perform a transitive reduction on the underlying DAG.
The transitive reduction of a graph is a graph with as few edges as possible with the same reachability as the original graph.
-
walk
(walker, walk_func)[source]¶ Walk the steps of the graph.
- Parameters
walker (Callable[[
runway.cfngin.dag.DAG
], Any]) – Function used to walk the steps.walk_func (Callable[[
Step
], Any]) – Function called with aStep
as the only argument for each step of the plan.
-
filtered
(step_names)[source]¶ Return a “filtered” version of this graph.
- Parameters
step_names (List[str]) – Steps to filter.
-
dumps
(indent=None)[source]¶ Output the graph as a json seralized string for storage.
- Parameters
indent (Optional[int]) – Number of spaces for each indentation.
- Returns
str
-
classmethod
from_dict
(graph_dict, context)[source]¶ Create a Graph from a graph dict.
- Parameters
graph_dict (Dict[str, List[str]]) – The dictionary used to create the graph.
context (
runway.cfngin.context.Context
) – Required to init stacks.
- Returns
-
-
class
runway.cfngin.plan.
Plan
(description, graph, context=None, reverse=False, require_unlocked=True)[source]¶ Bases:
object
A convenience class for working on a Graph.
-
context
¶ Context object.
Initialize class.
- Parameters
description (str) – Description of what the plan is going to do.
graph (
Graph
) – Local graph used for the plan.context (
runway.cfngin.context.Context
) – Context object.reverse (bool) – Transpose the graph for walking in reverse.
require_unlocked (bool) – Require the persistent graph to be unlocked before executing steps.
-
outline
(level=20, message='')[source]¶ Print an outline of the actions the plan is going to take.
The outline will represent the rough ordering of the steps that will be taken.
-
dump
(directory, context, provider=None)[source]¶ Output the rendered blueprint for all stacks in the plan.
- Parameters
directory (str) – Directory where files will be created.
context (
runway.cfngin.context.Contest
) – Current CFNgin context.provider (
runway.cfngin.providers.aws.default.Provider
) – Provider to use when resolving the blueprints.
-
execute
(*args, **kwargs)[source]¶ Walk each step in the underlying graph.
- Raises
PersistentGraphLocked – Raised if the persistent graph is locked prior to execution and this session did not lock it.
PlanFailed – Raised if any of the steps fail.
-
walk
(walker)[source]¶ Walk each step in the underlying graph, in topological order.
- Parameters
walker (func) – a walker function to be passed to
runway.cfngin.dag.DAG
to walk the graph.
-
property
lock_code
¶ Code to lock/unlock the persistent graph.
- Returns
str
-
property
step_names
¶ Return a list of all step names.
- Returns
List[str]
-