runway.cfngin.util module¶

CFNgin utilities.

runway.cfngin.util.camel_to_snake(name)[source]¶

Convert CamelCase to snake_case.

Parameters: name (str) – The name to convert from CamelCase to snake_case.
Returns: Converted string.
Return type: str

runway.cfngin.util.convert_class_name(kls)[source]¶

Get a string that represents a given class.

Parameters: kls (class) – The class being analyzed for its name.
Returns: The name of the given kls.
Return type: str

runway.cfngin.util.parse_zone_id(full_zone_id)[source]¶: Parse the returned hosted zone id and returns only the ID itself.

runway.cfngin.util.get_hosted_zone_by_name(client, zone_name)[source]¶

Get the zone id of an existing zone by name.

Parameters

client (botocore.client.Route53) – The connection used to interact with Route53’s API.
zone_name (str) – The name of the DNS hosted zone to create.

Returns

The Id of the Hosted Zone.

Return type

str

runway.cfngin.util.get_or_create_hosted_zone(client, zone_name)[source]¶

Get the Id of an existing zone, or create it.

Parameters

client (botocore.client.Route53) – The connection used to interact with Route53’s API.
zone_name (str) – The name of the DNS hosted zone to create.

Returns

The Id of the Hosted Zone.

Return type

str

class runway.cfngin.util.SOARecordText(record_text)[source]¶

Bases: object

Represents the actual body of an SOARecord.

Instantiate class.

class runway.cfngin.util.SOARecord(record)[source]¶

Bases: object

Represents an SOA record.

Instantiate class.

runway.cfngin.util.get_soa_record(client, zone_id, zone_name)[source]¶

Get the SOA record for zone_name from zone_id.

Parameters

client (boto3.client.Client) – The connection used to interact with Route53’s API.
zone_id (str) – The AWS Route53 zone id of the hosted zone to query.
zone_name (str) – The name of the DNS hosted zone to create.

Returns

An object representing the parsed SOA record returned from AWS Route53.

Return type

runway.cfngin.util.SOARecord

runway.cfngin.util.create_route53_zone(client, zone_name)[source]¶

Create the given zone_name if it doesn’t already exists.

Also sets the SOA negative caching TTL to something short (300 seconds).

Parameters

client (boto3.client.Client) – The connection used to interact with Route53’s API.
zone_name (str) – The name of the DNS hosted zone to create.

Returns

The zone id returned from AWS for the existing, or newly created zone.

Return type

str

runway.cfngin.util.merge_map(a, b)[source]¶

Recursively merge elements of argument b into argument a.

Primarily used for merging two dictionaries together, where dict b takes precedence over dict a. If 2 lists are provided, they are concatenated.

runway.cfngin.util.yaml_to_ordered_dict(stream, loader=<class 'yaml.loader.SafeLoader'>)[source]¶

yaml.load alternative with preserved dictionary order.

Parameters

stream (str) – YAML string to load.
loader (yaml.loader) – PyYAML loader class. Defaults to safe load.

Returns

Parsed YAML.

Return type

OrderedDict

runway.cfngin.util.uppercase_first_letter(string_)[source]¶: Return string with first character upper case.

runway.cfngin.util.cf_safe_name(name)[source]¶

Convert a name to a safe string for a CloudFormation resource.

Given a string, returns a name that is safe for use as a CloudFormation Resource. (ie: Only alphanumeric characters)

runway.cfngin.util.get_config_directory()[source]¶

Return the directory the config file is located in.

This enables us to use relative paths in config values.

runway.cfngin.util.read_value_from_path(value)[source]¶

Enable translators to read values from files.

The value can be referred to with the file:// prefix.

Example

conf_key: ${kms file://kms_value.txt}

runway.cfngin.util.get_client_region(client)[source]¶

Get the region from a boto3.client.Client object.

Parameters: client (boto3.client.Client) – The client to get the region from.
Returns: AWS region string.
Return type: str

runway.cfngin.util.get_s3_endpoint(client)[source]¶

Get the s3 endpoint for the given boto3.client.Client object.

Parameters: client (boto3.client.Client) – The client to get the endpoint from.
Returns: The AWS endpoint for the client.
Return type: str

runway.cfngin.util.s3_bucket_location_constraint(region)[source]¶

Return the appropriate LocationConstraint info for a new S3 bucket.

When creating a bucket in a region OTHER than us-east-1, you need to specify a LocationConstraint inside the CreateBucketConfiguration argument. This function helps you determine the right value given a given client.

Parameters: region (str) – The region where the bucket will be created in.
Returns: The string to use with the given client for creating a bucket.
Return type: str

runway.cfngin.util.ensure_s3_bucket(s3_client, bucket_name, bucket_region, persist_graph=False)[source]¶

Ensure an s3 bucket exists, if it does not then create it.

Parameters

s3_client (botocore.client.Client) – An s3 client used to verify and create the bucket.
bucket_name (str) – The bucket being checked/created.
bucket_region (str, optional) – The region to create the bucket in. If not provided, will be determined by s3_client’s region.
persist_graph (bool) – Check bucket for recommended settings. If creating a new bucket, it will be created with recommended settings.

runway.cfngin.util.parse_cloudformation_template(template)[source]¶

Parse CFN template string.

Leverages the vendored aws-cli yamlhelper to handle JSON or YAML templates.

Parameters: template (str) – The template body.

class runway.cfngin.util.Extractor(archive=None)[source]¶

Bases: object

Base class for extractors.

Instantiate class.

Parameters: archive (str) – Archive path.

set_archive(dir_name)[source]¶

Update archive filename to match directory name & extension.

Parameters: dir_name (str) – Archive directory name

static extension()[source]¶: Serve as placeholder; override this in subclasses.

class runway.cfngin.util.TarExtractor(archive=None)[source]¶

Bases: runway.cfngin.util.Extractor

Extracts tar archives.

Instantiate class.

Parameters: archive (str) – Archive path.

extract(destination)[source]¶: Extract the archive.

static extension()[source]¶: Return archive extension.

class runway.cfngin.util.TarGzipExtractor(archive=None)[source]¶

Bases: runway.cfngin.util.Extractor

Extracts compressed tar archives.

Instantiate class.

Parameters: archive (str) – Archive path.

extract(destination)[source]¶: Extract the archive.

static extension()[source]¶: Return archive extension.

class runway.cfngin.util.ZipExtractor(archive=None)[source]¶

Bases: runway.cfngin.util.Extractor

Extracts zip archives.

Instantiate class.

Parameters: archive (str) – Archive path.

extract(destination)[source]¶: Extract the archive.

static extension()[source]¶: Return archive extension.

class runway.cfngin.util.SourceProcessor(sources, cfngin_cache_dir=None)[source]¶

Bases: object

Makes remote python package sources available in current environment.

Process a config’s defined package sources.

Parameters

sources (Dict[str, Any]) – Package sources from CFNgin config dictionary.
cfngin_cache_dir (str) – Path where remote sources will be cached.

ISO8601_FORMAT = '%Y%m%dT%H%M%SZ'¶

create_cache_directories()[source]¶: Ensure that SourceProcessor cache directories exist.

get_package_sources()[source]¶: Make remote python packages available for local use.

fetch_local_package(config)[source]¶

Make a local path available to current CFNgin config.

Parameters: config (Dict[str, Any]) – ‘local’ path config dictionary.

fetch_s3_package(config)[source]¶

Make a remote S3 archive available for local use.

Parameters: config (Dict[str, Any]) – git config dictionary.

fetch_git_package(config)[source]¶

Make a remote git repository available for local use.

Parameters: config (Dict[str, Any]) – git config dictionary.

update_paths_and_config(config, pkg_dir_name, pkg_cache_dir=None)[source]¶

Handle remote source defined sys.paths & configs.

Parameters

config (Dict[str, Any]) – Git config dictionary.
pkg_dir_name (str) – directory Name of the CFNgin archive.
pkg_cache_dir (Optional[str]) – Fully qualified path to CFNgin cache cache directory.

static git_ls_remote(uri, ref)[source]¶

Determine the latest commit id for a given ref.

Parameters

uri (str) – Git URI.
ref (str) – Git ref.

Returns

A commit id

Return type

str

static determine_git_ls_remote_ref(config)[source]¶

Determine the ref to be used with the “git ls-remote” command.

Parameters: config (runway.cfngin.config.GitPackageSource) – Git config dictionary; ‘branch’ key is optional.
Returns: A branch reference or “HEAD”.
Return type: str

determine_git_ref(config)[source]¶

Determine the ref to be used for git checkout.

Parameters: config (Dict[str, Any]) – Git config dictionary.
Returns: A commit id or tag name.
Return type: str

static sanitize_uri_path(uri)[source]¶

Take a URI and converts it to a directory safe path.

Parameters: uri (str) – URI (e.g. http://example.com/cats).
Returns: Directory name for the supplied uri.
Return type: str

sanitize_git_path(uri, ref=None)[source]¶

Take a git URI and ref and converts it to a directory safe path.

Parameters

uri (str) – Git URI. (e.g. git@github.com:foo/bar.git)
ref (Optional[str]) – Git ref to be appended to the path.

Returns

Directory name for the supplied uri

Return type

str

runway.cfngin.util.stack_template_key_name(blueprint)[source]¶

Given a blueprint, produce an appropriate key name.

Parameters: blueprint (runway.cfngin.blueprints.base.Blueprint) – The blueprint object to create the key from.
Returns: Key name resulting from blueprint.
Return type: str