simple-aws-ssm-parameter-store 0.2.3

Quick Tutorial

1. Parameter Existence Testing

Check if a parameter exists without handling exceptions. The function returns None for non-existent parameters instead of raising ParameterNotFound exceptions.

import boto3
from simple_aws_ssm_parameter_store.api import get_parameter

ssm_client = boto3.client("ssm")

# Test if parameter exists
param = get_parameter(ssm_client, "/app/database/host")
if param is not None:
    print(f"Parameter exists with value: {param.value}")
else:
    print("Parameter does not exist")

2. Idempotent Parameter Deletion

Delete parameters safely without worrying about whether they exist. The function returns True if deletion occurred, False if the parameter didn’t exist.

from simple_aws_ssm_parameter_store import delete_parameter

# Safe to call multiple times
deleted = delete_parameter(ssm_client, "/app/temp/config")
if deleted:
    print("Parameter was deleted")
else:
    print("Parameter didn't exist")

# Call again - no exception raised
deleted = delete_parameter(ssm_client, "/app/temp/config")
print(f"Second deletion attempt: {deleted}")

3. Comprehensive Tag Management

Manage parameter tags with intuitive functions for getting, updating, and replacing tags.

from simple_aws_ssm_parameter_store.api import (
    get_parameter_tags,
    update_parameter_tags,
    put_parameter_tags,
    remove_parameter_tags
)

# Get all tags (returns empty dict if no tags)
tags = get_parameter_tags(ssm_client, "/app/config")
print(f"Current tags: {tags}")

# Add/update specific tags (partial update)
update_parameter_tags(ssm_client, "/app/config", {
    "Environment": "production",
    "Team": "platform"
})

# Replace all tags (full replacement)
put_parameter_tags(ssm_client, "/app/config", {
    "Environment": "production",
    "Owner": "alice"
})

# Remove specific tags
remove_parameter_tags(ssm_client, "/app/config", ["Team"])

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

Expected output progression:

Current tags: {}
After update: {"Environment": "production", "Team": "platform"}
After replacement: {"Environment": "production", "Owner": "alice"}
After removal: {"Environment": "production", "Owner": "alice"}
After clearing: {}

4. Smart Parameter Updates (Version Management)

Avoid unnecessary parameter writes and preserve version history with conditional updates. AWS SSM only keeps the last 100 versions - blindly updating parameters during debugging or deployment can quickly exhaust this limit and make older versions inaccessible.

from simple_aws_ssm_parameter_store.api import put_parameter_if_changed
from simple_aws_ssm_parameter_store.constants import ParameterType

# Smart update - only writes if value actually changed
before, after = put_parameter_if_changed(
    ssm_client=ssm_client,
    name="/app/database/host",
    value="prod-db.example.com",
    type=ParameterType.STRING,
    overwrite=True
)

# Check what happened
if before is None and after is not None:
    print(f"Parameter created: version {after.version}")
elif before is not None and after is None:
    print(f"No update needed - value unchanged (version {before.version})")
elif before is not None and after is not None:
    print(f"Parameter updated: {before.version} → {after.version}")

Example debugging scenario - avoiding version waste:

# During debugging, you might run this script multiple times
# Without conditional updates, each run would increment the version

# ❌ Bad: Always increments version (wastes version history)
ssm_client.put_parameter(
    Name="/app/config/debug",
    Value="same-value",
    Type="String",
    Overwrite=True  # This always creates new version
)

# ✅ Good: Only increments version when value actually changes
put_parameter_if_changed(
    ssm_client=ssm_client,
    name="/app/config/debug",
    value="same-value",
    type=ParameterType.STRING,
    overwrite=True  # Only used when value differs
)

Expected output progression:

# First run - parameter doesn't exist
Parameter created: version 1

# Second run - same value
No update needed - value unchanged (version 1)

# Third run - different value
Parameter updated: 1 → 2

# Fourth run - same value again
No update needed - value unchanged (version 2)

5. Working with Parameter Objects

Access parameter metadata through a rich Parameter object with convenient properties.

# Create a parameter first
ssm_client.put_parameter(
    Name="/app/database/password",
    Value="secret123",
    Type="SecureString"
)

# Get parameter with decryption
param = get_parameter(ssm_client, "/app/database/password", with_decryption=True)

print(f"Name: {param.name}")
print(f"Value: {param.value}")
print(f"Type: {param.type}")
print(f"Version: {param.version}")
print(f"Is SecureString: {param.is_secure_string_type}")
print(f"ARN: {param.arn}")

Expected output:

Name: /app/database/password
Value: secret123
Type: SecureString
Version: 1
Is SecureString: True
ARN: arn:aws:ssm:us-east-1:123456789012:parameter/app/database/password

Install

simple_aws_ssm_parameter_store is released on PyPI, so all you need is to:

$ pip install simple-aws-ssm-parameter-store

To upgrade to latest version:

$ pip install --upgrade simple-aws-ssm-parameter-store