sceptre package¶

class sceptre.NullHandler(level=0)[source]¶

Bases: Handler

emit(record)[source]¶

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

Subpackages¶

Submodules¶

sceptre.connection_manager module¶

sceptre.connection_manager

This module implements a ConnectionManager class, which simplifies and manages Boto3 calls.

class sceptre.connection_manager.ConnectionManager(region, profile=None, stack_name=None, iam_role=None, iam_role_session_duration=None)[source]¶

Bases: object

The Connection Manager is used to create boto3 clients for the various AWS services that Sceptre needs to interact with.

Parameters

profile (str) – The AWS credentials profile that should be used.
iam_role (str) – The iam_role that should be assumed in the account.
stack_name (str) – The CloudFormation stack name for this connection.
region (str) – The region to use.

call(service, command, kwargs=None, profile=None, region=None, stack_name=None, iam_role=None)[source]¶

Makes a thread-safe Boto3 client call.

Equivalent to boto3.client(<service>).<command>(**kwargs).

Parameters

service (str) – The Boto3 service to return a client for.
command (str) – The Boto3 command to call.
kwargs (dict) – The keyword arguments to supply to <command>.

Returns

The response from the Boto3 call.

Return type

dict

sceptre.context module¶

sceptre.context

This module implements the SceptreContext class which holds details about the paths used in a Sceptre project.

class sceptre.context.SceptreContext(project_path, command_path, user_variables=None, options=None, output_format=None, no_colour=False, ignore_dependencies=False, full_scan=False)[source]¶

Bases: object

SceptreContext is a place that holds data that is relevant to the project, including references to the project paths such as the path to your Sceptre project, templates path, config path, and the default names for your configuration files.

Parameters

project_path (str) – Absolute path to the base sceptre project folder
command_path (str) – The relative path to either StackGroup or Stack.
user_variables (dict) – Used to replace the value of anyvitem in a Config file with a value defined by the CLI flag or in a YAML variable file
options (dict) – The options specified in by the CLI command
output_format (str) – Specify the output format. Available formats: [yaml, json]
no_colour (bool) – Specify whether colouring should be used in the CLI output
full_scan (bool) – Specify whether folder scan the config files True for scan all the config files and False for scan only in the command path

clone()[source]¶

Creates a new, deep clone of the context with all the same values.

Return type: SceptreContext

command_path_is_stack()[source]¶

Returns True if the command path is a file.

Returns: True if the command path is a file
Return type: bool

full_command_path()[source]¶

Returns the command path in the format: project_path/config_path/command_path.

Returns: The absolute path to the path that will be executed
Return type: str

full_config_path()[source]¶

Returns the config path in the format: project_path/config_path.

Returns: The absolute path to the config directory
Return type: str

full_templates_path()[source]¶

Returns the templates path in the format: project_path/templates_path.

Returns: The absolute path to the templates directory
Return type: str

sceptre.exceptions module¶

exception sceptre.exceptions.CannotPruneStackError[source]¶

Bases: SceptreException

Error raised when an obsolete stack cannot be pruned because another stack depends on it that is not itself obsolete.

exception sceptre.exceptions.CannotUpdateFailedStackError[source]¶

Bases: SceptreException

Error raised when a failed stack is updated.

exception sceptre.exceptions.CircularDependenciesError[source]¶

Bases: SceptreException

Error raised if there are circular dependencies

exception sceptre.exceptions.ConfigFileNotFoundError[source]¶

Bases: SceptreException

Error raised when a config file does not exist.

exception sceptre.exceptions.DependencyDoesNotExistError[source]¶

Bases: SceptreException

Error raised when a dependency cannot be found

exception sceptre.exceptions.DependencyStackMissingOutputError[source]¶

Bases: SceptreException

Error raised if a dependency stack does not have the correct outputs.

exception sceptre.exceptions.DependencyStackNotLaunchedError[source]¶

Bases: SceptreException

Error raised when a dependency stack has not been launched

exception sceptre.exceptions.InvalidAWSCredentialsError[source]¶

Bases: SceptreException

Error raised when AWS credentials are invalid.

exception sceptre.exceptions.InvalidConfigFileError[source]¶

Bases: SceptreException

Error raised when a config file lacks mandatory keys.

exception sceptre.exceptions.InvalidHookArgumentSyntaxError[source]¶

Bases: SceptreException

Error raised if a hook’s argument syntax is invalid.

exception sceptre.exceptions.InvalidHookArgumentTypeError[source]¶

Bases: SceptreException

Error raised if a hook’s argument type is invalid.

exception sceptre.exceptions.InvalidHookArgumentValueError[source]¶

Bases: SceptreException

Error raised if a hook’s argument value is invalid.

exception sceptre.exceptions.InvalidSceptreDirectoryError[source]¶

Bases: SceptreException

Error raised if a sceptre directory is invalid.

exception sceptre.exceptions.PathConversionError[source]¶

Bases: SceptreException

Error raised when a path is unable to be converted.

exception sceptre.exceptions.ProjectAlreadyExistsError[source]¶

Bases: SceptreException

Error raised when Sceptre project already exists.

exception sceptre.exceptions.ProtectedStackError[source]¶

Bases: SceptreException

Error raised upon execution of an action under active protection

exception sceptre.exceptions.RetryLimitExceededError[source]¶

Bases: SceptreException

Error raised if the request limit is exceeded.

exception sceptre.exceptions.SceptreException[source]¶

Bases: Exception

Base class for all Sceptre errors

exception sceptre.exceptions.StackDoesNotExistError[source]¶

Bases: SceptreException

Error raised when a stack does not exist.

exception sceptre.exceptions.TemplateHandlerArgumentsInvalidError[source]¶

Bases: SceptreException

Error raised when the arguments passed to a Template Handler do not adhere to the specified JSON schema.

exception sceptre.exceptions.TemplateHandlerNotFoundError[source]¶

Bases: SceptreException

Error raised when a Template Handler of a certain type is not found

exception sceptre.exceptions.TemplateNotFoundError[source]¶

Bases: SceptreException

Error raised when a Template file is not found

exception sceptre.exceptions.TemplateSceptreHandlerError[source]¶

Bases: SceptreException

Error raised if sceptre_handler() is not defined correctly in the template.

exception sceptre.exceptions.UnknownHookTypeError[source]¶

Bases: SceptreException

Error raised if an unrecognised hook type is received.

exception sceptre.exceptions.UnknownStackChangeSetStatusError[source]¶

Bases: SceptreException

Error raised if an unknown stack change set status is received.

exception sceptre.exceptions.UnknownStackStatusError[source]¶

Bases: SceptreException

Error raised if an unknown stack status is received.

exception sceptre.exceptions.UnsupportedTemplateFileTypeError[source]¶

Bases: SceptreException

Error raised if an unsupported template file type is used.

exception sceptre.exceptions.VersionIncompatibleError[source]¶

Bases: SceptreException

Error raised if configuration incompatible with running version.

sceptre.helpers module¶

sceptre.helpers.get_external_stack_name(project_code, stack_name)[source]¶: Returns the name given to a stack in CloudFormation. :param project_code: The project code, as defined in config.yaml. :type project_code: str :param stack_name: The name of the stack. :type stack_name: str :returns: The name given to the stack in CloudFormation. :rtype: str

sceptre.helpers.mask_key(key)[source]¶

Returns an masked version of key.

Returned version has all but the last four characters are replaced with the character “*”.

Parameters: key (str) – The string to mask.
Returns: An masked version of the key
Return type: str

sceptre.helpers.normalise_path(path)[source]¶: Converts a path to use correct path separator. Raises an PathConversionError if the path has a trailing slash. :param path: A directory path :type path: str :raises: sceptre.exceptions.PathConversionError :returns: A normalised path with forward slashes. :returns: string

sceptre.helpers.null_context()[source]¶: A context manager that does nothing. This is identical to the nullcontext in py3.7+, but isn’t available in py3.6, so providing it here instead.

sceptre.helpers.sceptreise_path(path)[source]¶: Converts a path to use correct sceptre path separator. Raises an PathConversionError if the path has a trailing slash. :param path: A directory path :type path: str :raises: sceptre.exceptions.PathConversionError :returns: A normalised path with forward slashes. :returns: string

sceptre.stack module¶

sceptre.stack

This module implements a Stack class, which stores a Stack’s data.

class sceptre.stack.Stack(name, project_code, region, template_path=None, template_handler_config=None, template_bucket_name=None, template_key_prefix=None, required_version=None, parameters=None, sceptre_user_data=None, hooks=None, s3_details=None, iam_role=None, dependencies=None, role_arn=None, protected=False, tags=None, external_name=None, notifications=None, on_failure=None, profile=None, stack_timeout=0, iam_role_session_duration=0, ignore=False, obsolete=False, stack_group_config={})[source]¶

Bases: object

Stack stores information about a particular CloudFormation Stack.

Parameters

name (str) – The name of the Stack.
project_code (str) – A code which is prepended to the Stack names of all Stacks built by Sceptre.
template_path (Optional[str]) – The relative path to the CloudFormation, Jinja2 or Python template to build the Stack from. If this is filled, template_handler_config should not be filled.
template_handler_config (Optional[dict]) – Configuration for a Template Handler that can resolve its arguments to a template string. Should contain the type property to specify the type of template handler to load. Conflicts with template_path.
region (str) – The AWS region to build Stacks in.
template_bucket_name (Optional[str]) – The name of the S3 bucket the Template is uploaded to.
template_key_prefix (Optional[str]) – A prefix to the key used to store templates uploaded to S3
required_version (Optional[str]) – A PEP 440 compatible version specifier. If the Sceptre version does not fall within the given version requirement it will abort.
parameters (Optional[dict]) – The keys must match up with the name of the parameter. The value must be of the type as defined in the template.
sceptre_user_data (Optional[dict]) – Data passed into sceptre_handler(sceptre_user_data) function in Python templates or accessible under sceptre_user_data variable within Jinja2 templates.
hooks (Optional[Hook]) – A list of arbitrary shell or python commands or scripts to run.
s3_details (Optional[dict]) –
dependencies (Optional[List[Stack]]) – The relative path to the Stack, including the file extension of the Stack.
role_arn (Optional[str]) – The ARN of a CloudFormation Service Role that is assumed by CloudFormation to create, update or delete resources.
protected (bool) – Stack protection against execution.
tags (Optional[dict]) – CloudFormation Tags to be applied to the Stack.
external_name (Optional[str]) –
notifications (Optional[List[str]]) – SNS topic ARNs to publish Stack related events to. A maximum of 5 ARNs can be specified per Stack.
on_failure (Optional[str]) – This parameter describes the action taken by CloudFormation when a Stack fails to create.
iam_role (Optional[str]) – The ARN of a role for Sceptre to assume before interacting with the environment. If not supplied, Sceptre uses the user’s AWS CLI credentials.
profile (Optional[str]) – The name of the profile as defined in ~/.aws/config and ~/.aws/credentials.
stack_timeout (int) – A timeout in minutes before considering the Stack deployment as failed. After the specified timeout, the Stack will be rolled back. Specifying zero, as well as omitting the field, will result in no timeout. Supports only positive integer value.
ignore – If True, this stack will be ignored during launches (but it can be explicitly deployed with create, update, and delete commands.
obsolete – If True, this stack will operate the same as if ignore was set, but it will also be deleted if the prune command is invoked or the –prune option is used with the launch command.
iam_role_session_duration (int) – The session duration when Scetre assumes a role. If not supplied, Sceptre uses default value (3600 seconds)
stack_group_config (dict) – The StackGroup config for the Stack

property connection_manager: ConnectionManager¶

Returns the ConnectionManager for the stack, creating it if it has not yet been created.

Return type: ConnectionManager
Returns: ConnectionManager.

hooks¶

This is a descriptor class used to store an attribute that may contain Hook objects. Used to setup Hooks when added as a attribute. Supports nested dictionary and lists.

Parameters: name (str) – Attribute suffix used to store the property in the instance.

iam_role¶

This is a descriptor class used to store an attribute that may BE a single Resolver object. If it is a resolver, it will be resolved upon access of this property. When resolved, the resolved value will replace the resolver on the stack in order to avoid redundant resolutions.

Parameters: name (str) – Attribute suffix used to store the property in the instance.

notifications¶

This is a descriptor class used to store an attribute that may CONTAIN Resolver objects. Resolvers will be resolved upon access of this property. When resolvers are resolved, they will be replaced in the container with their resolved value, in order to avoid redundant resolutions.

Supports nested dictionary and lists.

Parameters: name (str) – Attribute suffix used to store the property in the instance.

parameters¶

This is a descriptor class used to store an attribute that may CONTAIN Resolver objects. Resolvers will be resolved upon access of this property. When resolvers are resolved, they will be replaced in the container with their resolved value, in order to avoid redundant resolutions.

Supports nested dictionary and lists.

Parameters: name (str) – Attribute suffix used to store the property in the instance.

role_arn¶

This is a descriptor class used to store an attribute that may BE a single Resolver object. If it is a resolver, it will be resolved upon access of this property. When resolved, the resolved value will replace the resolver on the stack in order to avoid redundant resolutions.

Parameters: name (str) – Attribute suffix used to store the property in the instance.

s3_details¶

This is a descriptor class used to store an attribute that may CONTAIN Resolver objects. Resolvers will be resolved upon access of this property. When resolvers are resolved, they will be replaced in the container with their resolved value, in order to avoid redundant resolutions.

Supports nested dictionary and lists.

Parameters: name (str) – Attribute suffix used to store the property in the instance.

sceptre_user_data¶

This is a descriptor class used to store an attribute that may CONTAIN Resolver objects. Resolvers will be resolved upon access of this property. When resolvers are resolved, they will be replaced in the container with their resolved value, in order to avoid redundant resolutions.

Supports nested dictionary and lists.

Parameters: name (str) – Attribute suffix used to store the property in the instance.

tags¶

This is a descriptor class used to store an attribute that may CONTAIN Resolver objects. Resolvers will be resolved upon access of this property. When resolvers are resolved, they will be replaced in the container with their resolved value, in order to avoid redundant resolutions.

Supports nested dictionary and lists.

Parameters: name (str) – Attribute suffix used to store the property in the instance.

property template¶

Returns the CloudFormation Template used to create the Stack.

Returns: The Stack’s template.
Return type: Template

template_bucket_name¶

This is a descriptor class used to store an attribute that may BE a single Resolver object. If it is a resolver, it will be resolved upon access of this property. When resolved, the resolved value will replace the resolver on the stack in order to avoid redundant resolutions.

Parameters: name (str) – Attribute suffix used to store the property in the instance.

template_handler_config¶

This is a descriptor class used to store an attribute that may CONTAIN Resolver objects. Resolvers will be resolved upon access of this property. When resolvers are resolved, they will be replaced in the container with their resolved value, in order to avoid redundant resolutions.

Supports nested dictionary and lists.

Parameters: name (str) – Attribute suffix used to store the property in the instance.

sceptre.stack_status module¶

sceptre.stack_status

This module implemets structs for simplified Stack status and simplified ChangeSet status values.

class sceptre.stack_status.StackChangeSetStatus[source]¶

Bases: object

StackChangeSetStatus stores simplified ChangeSet statuses.

DEFUNCT = 'defunct'¶

PENDING = 'pending'¶

READY = 'ready'¶

class sceptre.stack_status.StackStatus[source]¶

Bases: object

StackStatus stores simplified Stack statuses.

COMPLETE = 'complete'¶

FAILED = 'failed'¶

IN_PROGRESS = 'in progress'¶

PENDING = 'pending'¶

sceptre.stack_status_colourer module¶

sceptre.stack_status_colourer

This module implements a StackStatusColourer class, colours any Stack Statuses found in a given string.

class sceptre.stack_status_colourer.StackStatusColourer[source]¶

Bases: object

StackStatusColourer adds colours to stack statuses.

STACK_STATUS_CODES = {'CREATE_COMPLETE': '\x1b[32m', 'CREATE_FAILED': '\x1b[31m', 'CREATE_IN_PROGRESS': '\x1b[33m', 'DELETE_COMPLETE': '\x1b[32m', 'DELETE_FAILED': '\x1b[31m', 'DELETE_IN_PROGRESS': '\x1b[33m', 'PENDING': '\x1b[36m', 'ROLLBACK_COMPLETE': '\x1b[31m', 'ROLLBACK_FAILED': '\x1b[31m', 'ROLLBACK_IN_PROGRESS': '\x1b[33m', 'UPDATE_COMPLETE': '\x1b[32m', 'UPDATE_COMPLETE_CLEANUP_IN_PROGRESS': '\x1b[33m', 'UPDATE_FAILED': '\x1b[31m', 'UPDATE_IN_PROGRESS': '\x1b[33m', 'UPDATE_ROLLBACK_COMPLETE': '\x1b[32m', 'UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS': '\x1b[33m', 'UPDATE_ROLLBACK_FAILED': '\x1b[31m', 'UPDATE_ROLLBACK_IN_PROGRESS': '\x1b[33m'}¶

STACK_STATUS_PATTERN = re.compile('\\b(PENDING|CREATE_COMPLETE|CREATE_FAILED|CREATE_IN_PROGRESS|DELETE_COMPLETE|DELETE_FAILED|DELETE_IN_PROGRESS|ROLLBACK_COMPLETE|ROLLBACK_FAILED|ROLLBACK_IN_PROGRESS|UPDATE_COMPLETE|UPDATE_COMPLETE_CL)¶

colour(string)[source]¶

Colours all Stack Statueses in string.

The colours applied are defined in sceptre.stack_status_colourer.StackStatusColourer.STACK_STATUS_CODES

Parameters: string (str) – A string to colour.
Returns: The string with all stack status values coloured.
Return type: str

sceptre.template module¶

sceptre.template

This module implements a Template class, which stores a CloudFormation template and implements methods for uploading it to S3.

class sceptre.template.Template(name, handler_config, sceptre_user_data, stack_group_config, connection_manager=None, s3_details=None)[source]¶

Bases: object

Template represents an AWS CloudFormation template. It is responsible for loading, storing and optionally uploading local templates for use by CloudFormation.

Parameters

name (str) – The name of the template. Should be safe to use in filenames and not contain path segments.
handler_config (dict) – The configuration for a Template handler. Must contain a type.
sceptre_user_data (dict) – A dictionary of arbitrary data to be passed to a handler function in an external Python script.
stack_group_config (dict) – The StackGroup config for the Stack.
connection_manager (sceptre.connection_manager.ConnectionManager) –
s3_details (dict) –

property body¶

Represents body of the CloudFormation template.

Returns: The body of the CloudFormation template.
Return type: str

get_boto_call_parameter()[source]¶

Returns the CloudFormation template location.

Uploads the template to S3 and returns the object’s URL, or returns the template itself.

Returns: The boto call parameter for the template.
Return type: dict

upload_to_s3()[source]¶

Uploads the template to bucket_name and returns its URL.

The Template is uploaded with the bucket_key.

Returns: The URL of the Template object in S3.
Return type: str
Raises: botocore.exceptions.ClientError