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
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]