client¶

Enhanced boto3 SSM client functions.

This module provides high-level, Pythonic wrapper functions around the AWS SSM Parameter Store boto3 client operations. The functions handle error cases gracefully, provide better return values, and implement common patterns like existence testing and idempotent operations.

simple_aws_ssm_parameter_store.client.get_parameter(ssm_client: SSMClient, name: str, with_decryption: bool = False) → Parameter | None[source]¶

Get a parameter by name with built-in existence testing.

This function provides a convenient way to retrieve parameters while gracefully handling non-existent parameters. Unlike the raw boto3 client which raises exceptions for missing parameters, this function returns None, making it ideal for existence testing and conditional parameter access.

Example usage for existence testing:

param = get_parameter(ssm_client, "/my/param")
if param is not None:
    print("Parameter exists")
else:
    print("Parameter does not exist")

Ref:

get_parameter

Parameters:

ssm_client – SSM client
name – parameter name (e.g., “/app/database/host”)
with_decryption – whether to decrypt SecureString parameter values

Returns:

Parameter object if the parameter exists, None if it does not exist.

Put a parameter only if its value has changed (conditional write).

This function implements an optimized “get-then-put” operation that avoids unnecessary write operations when the parameter value hasn’t changed. It first retrieves the current parameter value and compares it with the desired value. Only if they differ (or if the parameter doesn’t exist) does it perform the actual write operation.

Why This Matters - Version History Preservation:

AWS SSM Parameter Store only retains the last 100 parameter versions. During development, debugging, or frequent deployments, blindly calling put_parameter() can rapidly consume this version history - even when values haven’t actually changed. This can make older parameter versions permanently inaccessible.

Consider a debugging scenario where you run a deployment script 50 times with the same configuration values. Without conditional updates, you’ve just consumed 50% of your version history for no benefit. This function prevents such waste.

Additional Benefits:

Performance: Reduces unnecessary API calls and write operations
Change tracking: Returns clear indication of whether a write occurred
Audit efficiency: Minimizes noise in CloudTrail logs from no-op updates
Version conservation: Preserves parameter version history for actual changes

The function handles SecureString parameters correctly by automatically enabling decryption when comparing values, ensuring accurate change detection even for encrypted parameters.

Example usage:

# Create or update parameter only if value changed
before, after = put_parameter_if_changed(
    ssm_client=client,
    name="/app/database/host",
    value="new-db-host.example.com",
    type=ParameterType.STRING
)

if after is not None:
    print(f"Parameter updated: version {after.version}")
else:
    print("No update needed - value unchanged")

Return value interpretation:

(None, Parameter): Parameter didn’t exist, was created
(Parameter, None): Parameter existed with same value, no update
(Parameter, Parameter): Parameter existed with different value, was updated

Ref:

put_parameter

Parameters:

ssm_client – SSM client
name – parameter name (e.g., “/app/database/host”)
value – parameter value to set
description – parameter description
type – parameter type (String, StringList, SecureString)
tier – parameter tier (Standard, Advanced, Intelligent-Tiering)
key_id – KMS key ID for SecureString encryption
overwrite – whether to overwrite existing parameter (required for updates)
allowed_pattern – regex pattern for parameter validation
tags – dictionary of tag key-value pairs
policies – parameter policies (JSON string)
data_type – parameter data type (e.g., “text”, “aws:ec2:image”)

Returns:

Tuple of (before_parameter, after_parameter) where: - before_parameter: Parameter object before operation (None if didn’t exist) - after_parameter: Parameter object after operation (None if no write occurred)

simple_aws_ssm_parameter_store.client.delete_parameter(ssm_client: SSMClient, name: str) → bool[source]¶

Delete a parameter by name with idempotent behavior.

This function provides idempotent parameter deletion - it can be called multiple times safely without raising errors. Unlike the raw boto3 client which raises ParameterNotFound exceptions, this function returns False for non-existent parameters, making it safe to use in cleanup operations and automation scripts.

The idempotent behavior ensures that:

If the parameter exists, it will be deleted and return True
If the parameter doesn’t exist, it returns False without raising an error
Multiple calls with the same parameter name are safe

Example usage in cleanup scripts:

# Safe to call even if parameter doesn't exist
deleted = delete_parameter(client, "/app/temp/config")
if deleted:
    print("Parameter was deleted")
else:
    print("Parameter did not exist")

Ref:

delete_parameter

Parameters:

ssm_client – SSM client
name – parameter name (e.g., “/app/database/host”)

Returns:

True if the parameter was deleted, False if it did not exist.

simple_aws_ssm_parameter_store.client.get_parameter_tags(ssm_client: SSMClient, name: str) → dict[str, str][source]¶

Get all tags associated with a parameter.

This function retrieves all tags for the specified parameter and returns them as a convenient key-value dictionary. If the parameter has no tags, an empty dictionary is returned.

Ref:

list_tags_for_resource

Parameters:

ssm_client – SSM client
name – parameter name (e.g., “/app/database/host”)

Returns:

Dictionary of tag key-value pairs. Empty dict if parameter has no tags.

simple_aws_ssm_parameter_store.client.remove_parameter_tags(ssm_client: SSMClient, name: str, tag_keys: list[str])[source]¶

Remove specific tags from a parameter by tag keys.

This function removes only the specified tag keys from the parameter, leaving other tags unchanged. It’s useful for selective tag cleanup without affecting the entire tag set.

Example:: # Remove only the “Environment” and “Team” tags remove_parameter_tags(client, “/app/config”, [“Environment”, “Team”])

Ref:

remove_tags_from_resource

Parameters:

ssm_client – SSM client
name – parameter name (e.g., “/app/database/host”)
tag_keys – list of tag keys to remove (e.g., [“Environment”, “Team”])

simple_aws_ssm_parameter_store.client.update_parameter_tags(ssm_client: SSMClient, name: str, tags: dict[str, str])[source]¶

Add or update specific tags on a parameter (partial update).

This function performs a partial update of parameter tags. It adds new tags and updates existing tags with the provided key-value pairs, while leaving other existing tags unchanged. This is useful for adding metadata without affecting the entire tag set.

Example:

# Add/update only specific tags, keeping others intact update_parameter_tags(client, “/app/config”, {

“Environment”: “production”, “LastUpdated”: “2024-01-15”

})

Ref:

add_tags_to_resource

Parameters:

ssm_client – SSM client
name – parameter name (e.g., “/app/database/host”)
tags – dictionary of tag key-value pairs to add/update

simple_aws_ssm_parameter_store.client.put_parameter_tags(ssm_client: SSMClient, name: str, tags: dict[str, str])[source]¶

Replace all parameter tags with the provided tag set (full replacement).

This function performs a complete replacement of all parameter tags. It removes all existing tags and replaces them with the provided tags. If an empty dictionary is provided, all tags are removed from the parameter.

Behavior:

Empty dict: Remove all existing tags from the parameter
Non-empty dict: Replace all existing tags with the provided tags

Example:

# Replace all tags with new set
put_parameter_tags(client, "/app/config", {
    "Environment": "production",
    "Owner": "platform-team"
})

# Remove all tags
put_parameter_tags(client, "/app/config", {})

Ref:

add_tags_to_resource

Parameters:

ssm_client – SSM client
name – parameter name (e.g., “/app/database/host”)
tags – dictionary of tag key-value pairs to set (empty dict removes all tags)