runway.cfngin.lookups.handlers.file module

File lookup.

class runway.cfngin.lookups.handlers.file.FileLookup

Bases: runway.lookups.handlers.base.LookupHandler

File lookup.

classmethod handle(value: str, **_: typing.Any) → typing.Any

Translate a filename into the file contents.

Parameters

value – Parameter(s) given to this lookup.

Fields should use the following format:

<codec>:<path>

Example:

# We've written a file to /some/path:
$ echo "hello there" > /some/path

# With CFNgin we would reference the contents of this file with the
# following
conf_key: ${file plain:file://some/path}

# The above would resolve to
conf_key: hello there

# Or, if we used wanted a base64 encoded copy of the file data
conf_key: ${file base64:file://some/path}

# The above would resolve to
conf_key: aGVsbG8gdGhlcmUK

Supported codecs:

plain

Plain Text

base64

Encode the plain text file at the given path with base64 prior to returning it.

parameterized

The same as plain, but additionally supports referencing template parameters to create userdata that’s supplemented with information from the template, as is commonly needed in EC2 UserData. For example, given a template parameter of BucketName, the file could contain the following text:

#!/bin/sh
aws s3 sync s3://{{BucketName}}/somepath /somepath

Then you could use something like this in the YAML config file:

UserData: ${file parameterized:/path/to/file}

Resulting in the UserData parameter being defined as:

{ "Fn::Join" : ["", [
    "#!/bin/sh\\naws s3 sync s3://",
    {"Ref" : "BucketName"},
    "/somepath /somepath"
]] }

parameterized-b64

The same as parameterized, with the results additionally wrapped in { "Fn::Base64": ... } , which is what you actually need for EC2 UserData.

When using parameterized-b64 for UserData, you should use a variable defined as such:

from troposphere import AWSHelperFn

"UserData": {
    "type": AWSHelperFn,
    "description": "Instance user data",
    "default": Ref("AWS::NoValue")
}

Then assign UserData in a LaunchConfiguration or Instance to self.variables["UserData"]. Note that we use AWSHelperFn as the type because the parameterized-b64 codec returns either a Base64 or a GenericHelperFn troposphere object.

json

Decode the file as JSON and return the resulting object

json-parameterized

Same as json, but applying templating rules from parameterized to every object value. Note that object keys are not modified. Example (an external PolicyDocument):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "some:Action"
            ],
            "Resource": "{{MyResource}}"
        }
    ]
}

yaml

Decode the file as YAML and return the resulting object. All strings are returned as unicode even in Python 2.

yaml-parameterized

Same as json-parameterized, but using YAML. Example:

Version: 2012-10-17
Statement:
  - Effect: Allow
    Action:
      - "some:Action"
    Resource: "{{MyResource}}"

classmethod dependencies(_LookupHandler__lookup_query: VariableValue) → Set[str]

Calculate any dependencies required to perform this lookup.

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

classmethod format_results(value: Any, get: Optional[str] = None, load: Optional[str] = None, transform: Optional[str] = None, **kwargs: Any) → Any

Format results to be returned by a lookup.

Parameters

• value – Data collected by the Lookup.

• get – Nested value to get from a dictionary like object.

• load – Parser to use to parse a formatted string before the get and transform method.

• transform – Convert the final value to a different data type before returning it.

Raises

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 load(value: Any, parser: Optional[str] = None, **kwargs: Any) → Any

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.

Parameters

• value – What is being loaded.

• parser – Name of the parser to use.

Returns

The loaded value.

classmethod parse(value: str) → Tuple[str, Dict[str, str]]

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

Parameters

value – The raw value passed to a lookup.

Returns

The lookup query and a dict of arguments

classmethod transform(value: Any, *, to_type: Optional[str] = 'str', **kwargs: Any) → Any

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.

Parameters

• value – What is to be transformed.

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

Returns

The transformed value.

runway.cfngin.lookups.handlers.file.parameterized_codec(raw: Union[bytes, str], b64: Literal[False] = False) → troposphere.GenericHelperFn

runway.cfngin.lookups.handlers.file.parameterized_codec(raw: Union[bytes, str], b64: Literal[True] = False) → troposphere.Base64

Parameterize a string, possibly encoding it as Base64 afterwards.

Parameters

• raw – String to be processed. Byte strings will be interpreted as UTF-8.

• b64 – Whether to wrap the output in a Base64 CloudFormation call.

Returns

Output to be included in a CloudFormation template.

Return type

troposphere.AWSHelperFn

class runway.cfngin.lookups.handlers.file.SafeUnicodeLoader(stream)

Bases: yaml.loader.SafeLoader

Safe unicode loader.

Initialize the scanner.

check_state_key(key)

Block special attributes/methods from being set in a newly created object, to prevent user-controlled methods from being called during deserialization

construct_yaml_str(node: typing.Any) → typing.Any

Construct yaml str.

runway.cfngin.lookups.handlers.file.yaml_codec(raw: str, parameterized: bool = False) → typing.Any

YAML codec.

runway.cfngin.lookups.handlers.file.json_codec(raw: str, parameterized: bool = False) → typing.Any

JSON codec.