runway.lookups.handlers.base module

Lookup Arguments

Arguments can be passed to Lookups to effect how they function.

To provide arguments to a Lookup, use a double-colon (::) after the query. Each argument is then defined as a key and value seperated with equals (=) and the arguments theselves are seperated with a comma (,). The arguments can have an optional space after the comma and before the next key to make them easier to read but this is not required. The value of all arguments are read as strings.


${var my_query::default=true, transform=bool}
${env MY_QUERY::default=1,transform=bool}

Each Lookup may have their own, specific arguments that it uses to modify its functionality or the value it returns. There is also a common set of arguments that all Lookups accept.

Common Lookup Arguments

default (Any)

If the Lookup is unable to find a value for the provided query, this value will be returned instead of raising an exception.

get (Optional[str])

Can be used on a dictionary type object to retrieve a specific piece of data. This is executed after the optional load step.

indent (Optional[int])

Number of spaces to use per indent level when transforming a dictionary type object to a string.

load (Optional[str])

Load the data to be processed by a Lookup using a specific parser. This is the first action taking on the data after it has been retrieved from its source. The data must be in a format that is supported by the parser in order for it to be used.


Loads a JSON seralizable string into a dictionary like object.


Loads the properties of a subclass of troposphere.BaseAWSObject into a dictionary.


Loads a YAML seralizable string into a dictionary like object.

region (Optional[str])

AWS region used when creating a boto3.Session to retrieve data. If not provided, the region currently being processed will be used. This can be specified to always get data from one region regardless of region is being deployed to.

transform (Optional[str])

Transform the data that will be returned by a Lookup into a different data type. This is the last action taking on the data before it is returned. Supports the following:


Converts any value to a string. The original data type determines the end result.

list, set, and tuple will become a comma delimited list

dict and anything else will become an escaped JSON string.


Converts a string or boolean value into a boolean.


  - parameters:
      some_variable: ${var some_value::default=my_value}
      comma_list: ${var my_list::default=undefined, transform=str}
class runway.lookups.handlers.base.LookupHandler[source]

Bases: object

Base class for lookup handlers.

classmethod dependencies(_lookup_data)[source]

Calculate any dependencies required to perform this lookup.

Note that lookup_data may not be (completely) resolved at this time.


lookup_data (VariableValue) – Parameter(s) given to this lookup.



classmethod format_results(value, get=None, load=None, transform=None, **kwargs)[source]

Format results to be returned by a lookup.

  • value (Any) – Data collected by the Lookup.

  • get (Optional[str]) – Nested value to get from a dictionary like object.

  • load (Optional[str]) – Parser to use to parse a formatted string before the get and transform method.

  • transform (Optional[str]) – Convert the final value to a different data type before returning it.


TypeError – If get is provided but the value value is not a dictionary like object.

Runs the following actions in order:

  1. load() if load is provided.

  2. runway.util.MutableMap.find() or dict.get() depending on the data type if get is provided.

  3. transform() if transform is provided.

classmethod handle(value, context, **kwargs)[source]

Perform the lookup.

  • value – Parameter(s) given to the lookup.

  • context – The current context object.

  • provider – Optional provider to use when handling the lookup.


(Any) Looked-up value.

classmethod parse(value)[source]

Parse the value passed to a lookup in a standardized way.


value – The raw value passed to a lookup.


The lookup query and a dict of arguments

classmethod load(value, parser=None, **kwargs)[source]

Load a formatted string or object into a python data type.

First action taken in format_results(). If a lookup needs to handling loading data to process it before it enters format_results(), is should use args.pop('load') to prevent the data from being loaded twice.

  • value – What is being loaded.

  • parser – Name of the parser to use.


The loaded value.

classmethod transform(value, to_type='str', **kwargs)[source]

Transform the result of a lookup into another datatype.

Last action taken in format_results(). If a lookup needs to handling transforming the data in a way that the base class can’t support it should overwrite this method of the base class to register different transform methods.

  • value – What is to be transformed.

  • to_type – The type the value will be transformed into.


The transformed value.