template¶

This module implements the core component CloudFormation Template. Many black magic features are provided.

class cottonformation.core.template.Template(AWSTemplateFormatVersion: str = '2010-09-09', Description: str = 'No description for this template', Metadata: dict = _Nothing.NOTHING, Parameters: Dict[str, cottonformation.core.model.Parameter] = _Nothing.NOTHING, Rules: Dict[str, cottonformation.core.model.Rule] = _Nothing.NOTHING, Mappings: Dict[str, cottonformation.core.model.Mapping] = _Nothing.NOTHING, Conditions: Dict[str, cottonformation.core.model.Condition] = _Nothing.NOTHING, Resources: Dict[str, cottonformation.core.model.Resource] = _Nothing.NOTHING, Outputs: Dict[str, cottonformation.core.model.Output] = _Nothing.NOTHING, Transform: List[Transform] = _Nothing.NOTHING, NestedStack: Dict[str, Template] = _Nothing.NOTHING, Groups: Dict[str, ResourceGroup] = _Nothing.NOTHING, deps_data_need_build_flag: bool = True, deps_on_data_cache: Dict[str, Set[str]] = _Nothing.NOTHING, deps_by_data_cache: Dict[str, Set[str]] = _Nothing.NOTHING, deps_sort_need_build_flag: bool = True, deps_sort_cache: Dict[str, int] = _Nothing.NOTHING)[source]¶

Represent an AWS CloudFormation template object.

Warning

Don’t ever directly edit the Template.Parameters, Template.Resources, Template.Outputs container dictionary. Please use the Template.add, Template.remove api. Because there’s a lot of logic been handled to maintain the state of the relationship.

Reference:

Template anatomy: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html

New in version 1.0.1.

property n_parameter¶: Return number of Parameters declared.

property n_resource¶: Return number of Resources declared.

property n_output¶: Return number of Outputs declared.

property n_rule¶: Return number of Rules declared.

property n_mapping¶: Return number of Mappings declared.

property n_condition¶: Return number of Conditions declared.

property n_transform¶: Return number of Transform declared.

property n_named_object¶: Return number of named object declared in this template. For example, Parameter, Resource, Output, Rule, Mapping, Condition are named object, because they have a logic id.

property deps_on_data: Dict[str, Set[str]]¶

Depends on data is a dictionary structure. It shows the dependency relationship in this way (child depends on parent):

{
    child_id_1: {parent_id_11, parent_id_12, ...},
    child_id_2: {parent_id_21, parent_id_22, ...},
    ...
}

property deps_by_data: Dict[str, Set[str]]¶

Depends on data is a dictionary structure. It shows the dependency relationship in this way (child depends on parent):

{
    parent_id_1: {child_id_11, child_id_12, ...},
    parent_id_2: {child_id_21, child_id_22, ...},
    ...
}

add_one(obj: Union[cottonformation.core.model.Parameter, cottonformation.core.model.Resource, cottonformation.core.model.Output, cottonformation.core.model.Rule, cottonformation.core.model.Mapping, cottonformation.core.model.Condition, cottonformation.core.model.ResourceGroup], add_or_update: bool = False, add_or_ignore: bool = False) → bool[source]¶

Add single object to Template. If there is a existing object with the same logic id and no flag is passed, exception will be raised.

Parameters

obj – The object you add to template.
add_or_update – if True, will overwrite other object with the same logic id
add_or_ignore – if True, will ignore and pass if there’s existing object with the same logic id

Returns

a boolean flag indicates that whether change is made.

Add an AWS object to the template. If the obj declared some dependency AWS Objects like Parameter, Mapping, Condition, it will also add those objects.

If there’s any logic id conflict include the root object or those dependency objects, the new object will overwrite the existing one.

This method is atomic. In other word, either all objects succeed or non.

remove_one(obj: Union[cottonformation.core.model.Parameter, cottonformation.core.model.Resource, cottonformation.core.model.Output, cottonformation.core.model.Rule, cottonformation.core.model.Mapping, cottonformation.core.model.Condition, cottonformation.core.model.ResourceGroup], ignore_not_exists: bool = False) → bool[source]¶

Remove single object from Template. If there is no a existing object with the same logic id and no flag is passed, exception will be raised.

Parameters

obj – The object you remove template.
ignore_not_exists – if True, will ignore and pass if there’s NO existing object with the same logic id

Returns

a boolean flag indicates that whether change is made.

Remove a AWS object from the template. If there are other objects depend on this object, it will also remove other objects.

This method is atomic. In other word, either all objects succeed or non.

add_nested_stack(stack: Union[str, cottonformation.res.cloudformation.Stack], template: cottonformation.core.template.Template) → bool[source]¶

Reference:

Nested Stack: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-nested-stacks.html

to_dict() → dict[source]¶: Serialize the template, convert it to python dict.

to_json(human_readable: bool = True) → str[source]¶: Convert template to json string.

to_json_file(path: str)[source]¶: Dump template to json file.

to_yml() → str[source]¶: Convert template to yaml string

to_yml_file(path: str)[source]¶: Dump template to yaml file.

post_init_hook()[source]¶: User can overwrite this method to extend cottonformation.Template

pre_serialize_hook()[source]¶: User can overwrite this method to extend cottonformation.Template

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

Batch tag all resources if supporting 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

classmethod from_many_objects(objects: Iterable[Union[cottonformation.core.model.Parameter, cottonformation.core.model.Resource, cottonformation.core.model.Output, cottonformation.core.model.Rule, cottonformation.core.model.Mapping, cottonformation.core.model.Condition, cottonformation.core.model.ResourceGroup]]) → cottonformation.core.template.Template[source]¶: A factory method can create a Template object from many AWS Objects.