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.

Parameters

graph1 (Graph) – Graph that graph2 will be merged into.
graph2 (Graph) – Graph that will be merged into graph1.

Returns

A combined graph.

Return type

Graph

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]

last_updated¶

Time when the step was last updated.

Type: float

logger¶

Logger for logging messages about the step.

Type: logging.LoggerAdaptor

stack¶

the stack associated with this step

Type: runway.cfngin.stack.Stack

status¶

The status of step.

Type: runway.cfngin.status.Status

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 step
fn (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.

run()[source]¶

Run this step until it has completed or been skipped.

Returns: bool

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.

complete()[source]¶: Shortcut for set_status(COMPLETE).

log_step()[source]¶: Construct a log message for a set and log it to the UI.

skip()[source]¶: Shortcut for set_status(SKIPPED).

submit()[source]¶: Shortcut for set_status(SUBMITTED).

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

Step

classmethod from_persistent_graph(graph_dict, context, fn=None, watch_func=None)[source]¶

Create a steps for a persistent graph dict.

Parameters

graph_dict (Dict[str, List[str]]) – A graph dict.
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 of runway.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.

Type: runway.cfngin.dag.DAG

steps¶

Dict with key of step name and value of Step.

Type: Dict[str, Step]

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 of Step for steps to initialize the Graph with. Note that if this is provided, a pre-configured runway.cfngin.dag.DAG that already includes these steps should also be provided..
dag (Optional[runway.cfngin.dag.DAG]) – An optional runway.cfngin.dag.DAG object. If one is not provided, a new one will be initialized.

add_step(step, add_dependencies=False, add_dependants=False)[source]¶

Add a step to the graph.

Parameters

step (Step) – The step to be added.
add_dependencies (bool) – Connect steps that need to be completed before this step.
add_dependants (bool) – Connect steps that require this step.

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.

Parameters

step (Step) – The step to be added.
add_dependencies (bool) – Connect steps that need to be completed before this step.
add_dependants (bool) – Connect steps that require this step.

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

connect(step, dep)[source]¶

Connect a dependency to a step.

Parameters

step (str) – Step name to add a dependency to.
dep (str) – Name of dependent step.

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.

See https://en.wikipedia.org/wiki/Transitive_reduction

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 a Step as the only argument for each step of the plan.

downstream(step_name)[source]¶: Return the direct dependencies of the given step.

transposed()[source]¶

Return a “transposed” version of this graph.

Useful for walking in reverse.

filtered(step_names)[source]¶

Return a “filtered” version of this graph.

Parameters: step_names (List[str]) – Steps to filter.

topological_sort()[source]¶

Perform a topological sort of the underlying DAG.

Returns: List[Step]

to_dict()[source]¶: Return the underlying DAG as a dictionary.

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

Graph

classmethod from_steps(steps)[source]¶

Create a Graph from Steps.

Parameters: steps (List[Step]) – Steps used to create the graph.
Returns: Graph

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.

Type: runway.cfngin.context.Context

description¶

Plan description.

Type: str

graph¶

Graph of the plan.

Type: Graph

id¶

UUID for the plan.

Type: str

reverse¶

The graph has been transposed for walking in reverse.

Type: bool

require_unlocked¶

Require the persistent graph to be unlocked before executing steps.

Type: bool

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.

Parameters

level (Optional[int]) – a valid log level that should be used to log the outline
message (Optional[str]) – a message that will be logged to the user after the outline has been logged.

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 steps¶

Return a list of all steps in the plan.

Returns: List[Step]

property step_names¶

Return a list of all step names.

Returns: List[str]

keys()[source]¶

Return a list of all step names.

Returns: List[str]