model¶

This module implements the AWS Object used in CloudFormation template.

class cottonformation.core.model.Validators[source]¶

Why this class?

In cottonformation, the data model is highly based on attr library. It ships with lots of convenient built-in validators However, the data type has to be defined first to use in the attr.validators.instance_of method.

instance_of(inst, attr, value, type_)[source]¶: Don’t use this function with partial,

tag_key_or_value(inst, attr, value)[source]¶: Validate if value represents a resource tag value.

class cottonformation.core.model.TypeHint[source]¶: Constant value hosting class for typehint

class cottonformation.core.model.IntrinsicFunction[source]¶

class cottonformation.core.model.Resource(id: str, ra_CreationPolicy: str = _Nothing.NOTHING, ra_DeletionPolicy: str = None, ra_DependsOn: Union[str, Resource, Parameter, Mapping, Condition, List[Union[str, Resource, Parameter, Mapping, Condition]]] = _Nothing.NOTHING, ra_Metadata: dict = _Nothing.NOTHING, ra_UpdatePolicy: str = None, ra_UpdateReplacePolicy: str = None, ra_Condition: Union[_BooleanCondition, str] = None)[source]¶

The base class for all AWS Resources.

New in version 1.0.1.

property DependsOn: List[Union[str, cottonformation.core.model.Resource, cottonformation.core.model.Parameter, cottonformation.core.model.Mapping, cottonformation.core.model.Condition]]¶: Public API to access the dependencies AWS Objects.

ref() → cottonformation.core.model.Ref[source]¶: Reference this Resource.

property tags_dict: collections.OrderedDict¶: Access the tag key value pairs as a Python dictionary.

classmethod support_tags() → bool[source]¶: Return a boolean value to indicate that whether this AWS Resource type support tagging.

update_tags(tags: Dict[str, str], mode_skip: bool = False, mode_overwrite: bool = False, mode_raise: bool = False) → Tuple[Dict[str, str], Dict[str, str]][source]¶

Update CloudFormation resource tags.

Parameters

tags – key value tags in python dictionary
mode_skip – if the key already exists, then skip it
mode_overwrite – if the key already exists, then overwrite it with new value
mode_raise – if the key already exists, then raise error

serialize() → dict[source]¶: Serialize the resource into CloudFormation JSON dictionary.

classmethod deserialize(data: dict)[source]¶: TODO: not implemented yet

class cottonformation.core.model.Parameter(id: str, Type: str, Default: Optional[str] = None, NoEcho: Optional[bool] = None, AllowedValues: Optional[List[Any]] = None, AllowedPattern: Optional[str] = None, MaxLength: Optional[int] = None, MinLength: Optional[int] = None, MaxValue: Optional[str] = None, MinValue: Optional[str] = None, Description: Optional[str] = None, ConstraintDescription: Optional[str] = None, DependsOn=_Nothing.NOTHING, value: Optional[Any] = None)[source]¶

Declare a CloudFormation parameter definition.

Reference:

Parameters: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html
AWS-specific parameter types: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html#aws-specific-parameter-types
SSM parameter types: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html#parameters-section-structure-grouping

New in version 1.0.1.

class cottonformation.core.model.Export(Name: Union[str, dict, cottonformation.core.model.IntrinsicFunction])[source]¶

The export value object for cross stack reference.

Reference:

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-importvalue.html

New in version 1.0.1.

class cottonformation.core.model.Output(id: str, Value: Any, Description: Union[str, dict, IntrinsicFunction] = None, Export: _CountingAttr(counter=52, _default=None, repr=True, eq=True, order=True, hash=None, init=True, on_setattr=None, alias=None, metadata={}) = None, DependsOn=_Nothing.NOTHING)[source]¶

Declare a CloudFormation Output definition.

You can also explicitly define dependencies for output object.

New in version 1.0.1.

class cottonformation.core.model.Tag(p_Key: Union[str, dict, IntrinsicFunction], p_Value: Union[str, dict, IntrinsicFunction, cottonformation.core.model.Parameter, ImportValue])[source]¶

The AWS Resource Tag object. Note that some AWS Resource use different data structure to define resource tags.

New in version 1.0.1.

classmethod make_many(dict_data: Optional[dict] = None, **kwargs) → List[cottonformation.core.model.Tag][source]¶

A factory method to make many tags.

Parameters: dict_data – key value pairs of the tags.
Returns: list of tags

class cottonformation.core.model.Ref(param_or_res: Union[str, cottonformation.core.model.Parameter, cottonformation.core.model.Resource])[source]¶

Reference:

Ref: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-ref.html

New in version 1.0.1.

class cottonformation.core.model.Base64(value: Union[str, dict, cottonformation.core.model.IntrinsicFunction])[source]¶

Reference:

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-base64.html

New in version 1.0.1.

class cottonformation.core.model.Cidr(ip_block: Union[str, dict, cottonformation.core.model.IntrinsicFunction], count: Union[int, dict, cottonformation.core.model.IntrinsicFunction], cidr_bits: Union[int, dict, cottonformation.core.model.IntrinsicFunction])[source]¶

Reference:

Fn::Cidr: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-cidr.html

New in version 1.0.1.

class cottonformation.core.model.FindInMap(map_name: Union[str, dict, cottonformation.core.model.IntrinsicFunction], top_level_key: Union[str, dict, cottonformation.core.model.IntrinsicFunction], second_level_key: Union[str, dict, cottonformation.core.model.IntrinsicFunction])[source]¶

Reference:

Fn::FindInMap: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-findinmap.html

New in version 1.0.1.

class cottonformation.core.model.GetAtt(resource: Union[str, cottonformation.core.model.Resource], attr_name: str)[source]¶

Reference:

Fn::GetAtt: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getatt.html

New in version 1.0.1.

class cottonformation.core.model.GetAZs(region: Union[str, dict, cottonformation.core.model.IntrinsicFunction] = '')[source]¶

Reference:

Fn::GetAZs: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-getavailabilityzones.html
Region and Az information: https://aws.amazon.com/about-aws/global-infrastructure/regions_az/

New in version 1.0.1.

class cottonformation.core.model.ImportValue(name: Union[str, dict, cottonformation.core.model.IntrinsicFunction])[source]¶

Reference:

Fn::ImportValue: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-importvalue.html

New in version 1.0.1.

class cottonformation.core.model.Join(delimiter: Union[str, dict, cottonformation.core.model.IntrinsicFunction, cottonformation.core.model.Parameter], list_of_values: List[Union[str, dict, cottonformation.core.model.IntrinsicFunction, cottonformation.core.model.Parameter, cottonformation.core.model.Resource]])[source]¶

Reference:

Fn::Join: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-join.html

New in version 1.0.1.

class cottonformation.core.model.Sub(string: str, data: dict)[source]¶

Example:

>>> Sub("${project}-${env}", dict(project="my_app", env="dev")).serialize()
{
    "Fn::Sub": [
        "${project}-${env}",
        {
            "project": "my_app",
            "env": "dev",
        }
    ]
}

Reference:

Fn::Sub: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-sub.html

New in version 1.0.1.

classmethod from_params(f_string, *params: cottonformation.core.model.Parameter)[source]¶

A helper factory method to construct a Sub syntax from the popular positioning formatted string literals and multiple Parameter.

Sample usage:

>>> p_project_name = Parameter("ProjName", Type=Parameter.TypeEnum.String)
>>> p_stage = Parameter("Stage", Type=Parameter.TypeEnum.String)
>>> sub = Sub.from_params("{}-{}-main-ec2-instance", p_project_name, p_stage)
>>> sub.serialize() # the sub object is equavilent to
{
    "Fn::Sub": [
        "${ProjName}-${Stage}",
        {
            "ProjName": {"Ref": "ProjName"},
            "Stage": {"Ref": "Stage"}
        }
    ]
}

class cottonformation.core.model.Select(index, list_of_objects: Union[list, cottonformation.core.model.IntrinsicFunction])[source]¶

Reference:

Fn::Select: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-select.html

New in version 1.0.1.

class cottonformation.core.model.Split(delimiter: Union[str, dict, cottonformation.core.model.IntrinsicFunction], source_string: Union[str, dict, cottonformation.core.model.IntrinsicFunction])[source]¶

Reference:

Fn::Split: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-split.html

New in version 1.0.1.

class cottonformation.core.model.Mapping(id: str, DependsOn=_Nothing.NOTHING)[source]¶

Reference:

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html

New in version 1.0.1.

class cottonformation.core.model.Condition[source]¶

Ref:

New in version 1.0.1.

class cottonformation.core.model.Equals(id: str, value_one: Union[cottonformation.core.model.AwsObject, Any], value_two: Union[cottonformation.core.model.AwsObject, Any], DependsOn=_Nothing.NOTHING)[source]¶

Compares if two values are equal. Returns true if the two values are equal or false if they aren’t.

Parameters

value_one – the value can be generic value, Parameter / Resource, Reference of Parameter / Resource, Intrinsic Function.
value_two – same as value_one

Ref:

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#intrinsic-function-reference-conditions-equals

New in version 1.0.1.

class cottonformation.core.model.Not(id: str, condition: Union[cottonformation.core.model._BooleanCondition, dict])[source]¶

Returns true for a condition that evaluates to false or returns false for a condition that evaluates to true. Fn::Not acts as a NOT operator.

Parameters: condition – can be an _BooleanCondition object, or a serialized dictionary view of a condition.

Ref:

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#intrinsic-function-reference-conditions-not

New in version 1.0.1.

class cottonformation.core.model.And(id: str, conditions: List[Union[cottonformation.core.model._BooleanCondition, dict]], DependsOn=_Nothing.NOTHING)[source]¶

Logic And

Parameters: conditions – can be list of _BooleanCondition object, or a serialized dictionary view of a condition.

Ref:

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#intrinsic-function-reference-conditions-and

New in version 1.0.1.

class cottonformation.core.model.Or(id: str, conditions: List[Union[cottonformation.core.model._BooleanCondition, dict]], DependsOn=_Nothing.NOTHING)[source]¶

Logic Or

Parameters: conditions – can be list of _BooleanCondition object, or a serialized dictionary view of a condition.

Ref:

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#intrinsic-function-reference-conditions-or

New in version 1.0.1.

class cottonformation.core.model.If(condition_name: Union[cottonformation.core.model._BooleanCondition, str], value_if_true, value_if_false, DependsOn=_Nothing.NOTHING)[source]¶

Returns one value if the specified condition evaluates to true and another value if the specified condition evaluates to false.

If Condition should be used directly for value assignment.

Ref:

Official Doc: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/intrinsic-function-reference-conditions.html#intrinsic-function-reference-conditions-if

New in version 1.0.1.

class cottonformation.core.model.Rule(id: str, DependsOn: Union[str, cottonformation.core.model.Resource, cottonformation.core.model.Parameter, cottonformation.core.model.Mapping, cottonformation.core.model.Condition, List[Union[str, cottonformation.core.model.Resource, cottonformation.core.model.Parameter, cottonformation.core.model.Mapping, cottonformation.core.model.Condition]]] = _Nothing.NOTHING)[source]¶

Reference:

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/rules-section-structure.html

New in version 1.0.1.

class cottonformation.core.model.Transform[source]¶

Reference:

https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-section-structure.html

New in version 1.0.1.

class cottonformation.core.model.ResourceGroup(id: str = '__never_exists__', DependsOn=_Nothing.NOTHING)[source]¶: A custom container to group multiple AwsObject together. So you can add / remove all item in resource group in one API call.

New in version 1.0.1.

cottonformation.core.model.get_key_value_dict(obj: attr._make.attrs) → dict[source]¶: In serialization (convert object to dict data), since we are trying to unfold data in format of cloudformation, not the native python dict view. I don’t want attr.asdict automatically unfold the nested object in a way I don’t want.

cottonformation.core.model.remove_id_and_empty(dct: dict) → dict[source]¶

In serialization (convert object to dict data), a common case is we ignore the id field and those key-valur pair having None value or empty collection object. This helper function does that.

Example:

>>> remove_id_and_empty({
...     "id": 1, # id field
...     "key": "good_key",
...     "good_value": False,
...     "bad_value": None,
...     "good_list": [1, 2, 3],
...     "bad_list": [],
...     "good_dict": {"a": 1},
...     "bad_dict": {},
... })
{
    "key": "good_key,
    "good_value": False,
    "good_list": [1, 2, 3],
    "good_dict": {"a": 1},
}

cottonformation.core.model.get_id(obj_or_id: Union[str, cottonformation.core.model.Parameter, cottonformation.core.model.Resource, cottonformation.core.model.Output, cottonformation.core.model.Rule, cottonformation.core.model.Mapping, cottonformation.core.model.Condition]) → str[source]¶: Get the logic id string.

cottonformation.core.model.serialize(obj: Union[cottonformation.core.model.AwsObject, dict, Any]) → Any[source]¶

A universal api that convert anything to json serializable python dictionary.

It is for CloudFormation template serialization.

cottonformation.core.model.eval(obj: Union[cottonformation.core.model.AwsObject, dict, str, Any]) → Any[source]¶

A universal api that convert anything to an object that represent its value.

It is for referencing the “Value” of the object.