.. image:: https://readthedocs.org/projects/simple-aws-ssm-parameter-store/badge/?version=latest
:target: https://simple-aws-ssm-parameter-store.readthedocs.io/en/latest/
:alt: Documentation Status
.. image:: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/actions/workflows/main.yml/badge.svg
:target: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/actions?query=workflow:CI
.. image:: https://codecov.io/gh/MacHu-GWU/simple_aws_ssm_parameter_store-project/branch/main/graph/badge.svg
:target: https://codecov.io/gh/MacHu-GWU/simple_aws_ssm_parameter_store-project
.. image:: https://img.shields.io/pypi/v/simple-aws-ssm-parameter-store.svg
:target: https://pypi.python.org/pypi/simple-aws-ssm-parameter-store
.. image:: https://img.shields.io/pypi/l/simple-aws-ssm-parameter-store.svg
:target: https://pypi.python.org/pypi/simple-aws-ssm-parameter-store
.. image:: https://img.shields.io/pypi/pyversions/simple-aws-ssm-parameter-store.svg
:target: https://pypi.python.org/pypi/simple-aws-ssm-parameter-store
.. image:: https://img.shields.io/badge/✍️_Release_History!--None.svg?style=social&logo=github
:target: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/blob/main/release-history.rst
.. image:: https://img.shields.io/badge/⭐_Star_me_on_GitHub!--None.svg?style=social&logo=github
:target: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project
------
.. image:: https://img.shields.io/badge/Link-API-blue.svg
:target: https://simple-aws-ssm-parameter-store.readthedocs.io/en/latest/py-modindex.html
.. image:: https://img.shields.io/badge/Link-Install-blue.svg
:target: `install`_
.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg
:target: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project
.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg
:target: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/issues
.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg
:target: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/issues
.. image:: https://img.shields.io/badge/Link-Download-blue.svg
:target: https://pypi.org/pypi/simple-aws-ssm-parameter-store#files
Welcome to ``simple_aws_ssm_parameter_store`` Documentation
==============================================================================
.. image:: https://simple-aws-ssm-parameter-store.readthedocs.io/en/latest/_static/simple_aws_ssm_parameter_store-logo.png
:target: https://simple-aws-ssm-parameter-store.readthedocs.io/en/latest/
``simple_aws_ssm_parameter_store`` is a Pythonic wrapper library for AWS SSM Parameter Store that enhances the standard boto3 client with better error handling, existence testing, idempotent operations, and comprehensive tag management. Instead of dealing with exceptions for missing parameters or complex tag operations, this library provides intuitive functions that return meaningful values and handle edge cases gracefully.
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.
.. code-block:: python
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.
.. code-block:: python
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.
.. code-block:: python
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:
.. code-block:: console
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.
.. code-block:: python
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:
.. code-block:: python
# 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:
.. code-block:: console
# 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.
.. code-block:: python
# 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:
.. code-block:: console
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:
Install
------------------------------------------------------------------------------
``simple_aws_ssm_parameter_store`` is released on PyPI, so all you need is to:
.. code-block:: console
$ pip install simple-aws-ssm-parameter-store
To upgrade to latest version:
.. code-block:: console
$ pip install --upgrade simple-aws-ssm-parameter-store
Raw data
{
"_id": null,
"home_page": null,
"name": "simple-aws-ssm-parameter-store",
"maintainer": "Sanhe Hu",
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": "husanhe@email.com",
"keywords": null,
"author": "Sanhe Hu",
"author_email": "husanhe@email.com",
"download_url": "https://files.pythonhosted.org/packages/45/4d/d817df4fd5f4ccb40cf42a433c6d126cc5c142f4e63a5e5fdfd5f2024a1e/simple_aws_ssm_parameter_store-0.2.2.tar.gz",
"platform": null,
"description": "\n.. image:: https://readthedocs.org/projects/simple-aws-ssm-parameter-store/badge/?version=latest\n :target: https://simple-aws-ssm-parameter-store.readthedocs.io/en/latest/\n :alt: Documentation Status\n\n.. image:: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/actions/workflows/main.yml/badge.svg\n :target: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/actions?query=workflow:CI\n\n.. image:: https://codecov.io/gh/MacHu-GWU/simple_aws_ssm_parameter_store-project/branch/main/graph/badge.svg\n :target: https://codecov.io/gh/MacHu-GWU/simple_aws_ssm_parameter_store-project\n\n.. image:: https://img.shields.io/pypi/v/simple-aws-ssm-parameter-store.svg\n :target: https://pypi.python.org/pypi/simple-aws-ssm-parameter-store\n\n.. image:: https://img.shields.io/pypi/l/simple-aws-ssm-parameter-store.svg\n :target: https://pypi.python.org/pypi/simple-aws-ssm-parameter-store\n\n.. image:: https://img.shields.io/pypi/pyversions/simple-aws-ssm-parameter-store.svg\n :target: https://pypi.python.org/pypi/simple-aws-ssm-parameter-store\n\n.. image:: https://img.shields.io/badge/\u270d\ufe0f_Release_History!--None.svg?style=social&logo=github\n :target: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/blob/main/release-history.rst\n\n.. image:: https://img.shields.io/badge/\u2b50_Star_me_on_GitHub!--None.svg?style=social&logo=github\n :target: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project\n\n------\n\n.. image:: https://img.shields.io/badge/Link-API-blue.svg\n :target: https://simple-aws-ssm-parameter-store.readthedocs.io/en/latest/py-modindex.html\n\n.. image:: https://img.shields.io/badge/Link-Install-blue.svg\n :target: `install`_\n\n.. image:: https://img.shields.io/badge/Link-GitHub-blue.svg\n :target: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project\n\n.. image:: https://img.shields.io/badge/Link-Submit_Issue-blue.svg\n :target: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/issues\n\n.. image:: https://img.shields.io/badge/Link-Request_Feature-blue.svg\n :target: https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/issues\n\n.. image:: https://img.shields.io/badge/Link-Download-blue.svg\n :target: https://pypi.org/pypi/simple-aws-ssm-parameter-store#files\n\n\nWelcome to ``simple_aws_ssm_parameter_store`` Documentation\n==============================================================================\n.. image:: https://simple-aws-ssm-parameter-store.readthedocs.io/en/latest/_static/simple_aws_ssm_parameter_store-logo.png\n :target: https://simple-aws-ssm-parameter-store.readthedocs.io/en/latest/\n\n``simple_aws_ssm_parameter_store`` is a Pythonic wrapper library for AWS SSM Parameter Store that enhances the standard boto3 client with better error handling, existence testing, idempotent operations, and comprehensive tag management. Instead of dealing with exceptions for missing parameters or complex tag operations, this library provides intuitive functions that return meaningful values and handle edge cases gracefully.\n\n\nQuick Tutorial\n------------------------------------------------------------------------------\n**1. Parameter Existence Testing**\n\nCheck if a parameter exists without handling exceptions. The function returns ``None`` for non-existent parameters instead of raising ``ParameterNotFound`` exceptions.\n\n.. code-block:: python\n\n import boto3\n from simple_aws_ssm_parameter_store.api import get_parameter\n\n ssm_client = boto3.client(\"ssm\")\n \n # Test if parameter exists\n param = get_parameter(ssm_client, \"/app/database/host\")\n if param is not None:\n print(f\"Parameter exists with value: {param.value}\")\n else:\n print(\"Parameter does not exist\")\n\n**2. Idempotent Parameter Deletion**\n\nDelete parameters safely without worrying about whether they exist. The function returns ``True`` if deletion occurred, ``False`` if the parameter didn't exist.\n\n.. code-block:: python\n\n from simple_aws_ssm_parameter_store import delete_parameter\n\n # Safe to call multiple times\n deleted = delete_parameter(ssm_client, \"/app/temp/config\")\n if deleted:\n print(\"Parameter was deleted\")\n else:\n print(\"Parameter didn't exist\")\n \n # Call again - no exception raised\n deleted = delete_parameter(ssm_client, \"/app/temp/config\")\n print(f\"Second deletion attempt: {deleted}\")\n\n**3. Comprehensive Tag Management**\n\nManage parameter tags with intuitive functions for getting, updating, and replacing tags.\n\n.. code-block:: python\n\n from simple_aws_ssm_parameter_store.api import (\n get_parameter_tags,\n update_parameter_tags, \n put_parameter_tags,\n remove_parameter_tags\n )\n\n # Get all tags (returns empty dict if no tags)\n tags = get_parameter_tags(ssm_client, \"/app/config\")\n print(f\"Current tags: {tags}\")\n\n # Add/update specific tags (partial update)\n update_parameter_tags(ssm_client, \"/app/config\", {\n \"Environment\": \"production\",\n \"Team\": \"platform\"\n })\n\n # Replace all tags (full replacement)\n put_parameter_tags(ssm_client, \"/app/config\", {\n \"Environment\": \"production\",\n \"Owner\": \"alice\"\n })\n\n # Remove specific tags\n remove_parameter_tags(ssm_client, \"/app/config\", [\"Team\"])\n\n # Remove all tags\n put_parameter_tags(ssm_client, \"/app/config\", {})\n\nExpected output progression:\n\n.. code-block:: console\n\n Current tags: {}\n After update: {\"Environment\": \"production\", \"Team\": \"platform\"}\n After replacement: {\"Environment\": \"production\", \"Owner\": \"alice\"}\n After removal: {\"Environment\": \"production\", \"Owner\": \"alice\"}\n After clearing: {}\n\n**4. Smart Parameter Updates (Version Management)**\n\nAvoid 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.\n\n.. code-block:: python\n\n from simple_aws_ssm_parameter_store.api import put_parameter_if_changed\n from simple_aws_ssm_parameter_store.constants import ParameterType\n\n # Smart update - only writes if value actually changed\n before, after = put_parameter_if_changed(\n ssm_client=ssm_client,\n name=\"/app/database/host\",\n value=\"prod-db.example.com\",\n type=ParameterType.STRING,\n overwrite=True\n )\n\n # Check what happened\n if before is None and after is not None:\n print(f\"Parameter created: version {after.version}\")\n elif before is not None and after is None:\n print(f\"No update needed - value unchanged (version {before.version})\")\n elif before is not None and after is not None:\n print(f\"Parameter updated: {before.version} \u2192 {after.version}\")\n\nExample debugging scenario - avoiding version waste:\n\n.. code-block:: python\n\n # During debugging, you might run this script multiple times\n # Without conditional updates, each run would increment the version\n \n # \u274c Bad: Always increments version (wastes version history)\n ssm_client.put_parameter(\n Name=\"/app/config/debug\",\n Value=\"same-value\",\n Type=\"String\",\n Overwrite=True # This always creates new version\n )\n \n # \u2705 Good: Only increments version when value actually changes\n put_parameter_if_changed(\n ssm_client=ssm_client,\n name=\"/app/config/debug\", \n value=\"same-value\",\n type=ParameterType.STRING,\n overwrite=True # Only used when value differs\n )\n\nExpected output progression:\n\n.. code-block:: console\n\n # First run - parameter doesn't exist\n Parameter created: version 1\n \n # Second run - same value\n No update needed - value unchanged (version 1)\n \n # Third run - different value \n Parameter updated: 1 \u2192 2\n \n # Fourth run - same value again\n No update needed - value unchanged (version 2)\n\n**5. Working with Parameter Objects**\n\nAccess parameter metadata through a rich Parameter object with convenient properties.\n\n.. code-block:: python\n\n # Create a parameter first\n ssm_client.put_parameter(\n Name=\"/app/database/password\",\n Value=\"secret123\",\n Type=\"SecureString\"\n )\n\n # Get parameter with decryption\n param = get_parameter(ssm_client, \"/app/database/password\", with_decryption=True)\n \n print(f\"Name: {param.name}\")\n print(f\"Value: {param.value}\")\n print(f\"Type: {param.type}\")\n print(f\"Version: {param.version}\")\n print(f\"Is SecureString: {param.is_secure_string_type}\")\n print(f\"ARN: {param.arn}\")\n\nExpected output:\n\n.. code-block:: console\n\n Name: /app/database/password\n Value: secret123\n Type: SecureString\n Version: 1\n Is SecureString: True\n ARN: arn:aws:ssm:us-east-1:123456789012:parameter/app/database/password\n\n\n.. _install:\n\nInstall\n------------------------------------------------------------------------------\n\n``simple_aws_ssm_parameter_store`` is released on PyPI, so all you need is to:\n\n.. code-block:: console\n\n $ pip install simple-aws-ssm-parameter-store\n\nTo upgrade to latest version:\n\n.. code-block:: console\n\n $ pip install --upgrade simple-aws-ssm-parameter-store\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Pythonic wrapper library for AWS SSM Parameter Store with enhanced error handling, existence testing, idempotent operations, and comprehensive tag management.",
"version": "0.2.2",
"project_urls": {
"Changelog": "https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/blob/main/release-history.rst",
"Documentation": "https://simple-aws-ssm-parameter-store.readthedocs.io/en/latest/",
"Download": "https://pypi.org/pypi/simple-aws-ssm-parameter-store#files",
"Homepage": "https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project",
"Issues": "https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/issues",
"Repository": "https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "96aef035f1bd4fca159120a5561aef08f396d7cdd1b653ddae52f763493fec95",
"md5": "b89019f817e7b6a0a08bbea923865575",
"sha256": "0b4d6fe49aafb146c6723ed56b4090ae60bd9caa8fd14b229bb177928c94585a"
},
"downloads": -1,
"filename": "simple_aws_ssm_parameter_store-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b89019f817e7b6a0a08bbea923865575",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 15990,
"upload_time": "2025-08-18T20:25:38",
"upload_time_iso_8601": "2025-08-18T20:25:38.083690Z",
"url": "https://files.pythonhosted.org/packages/96/ae/f035f1bd4fca159120a5561aef08f396d7cdd1b653ddae52f763493fec95/simple_aws_ssm_parameter_store-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "454dd817df4fd5f4ccb40cf42a433c6d126cc5c142f4e63a5e5fdfd5f2024a1e",
"md5": "ed91a374fc6fc82c80d09344f0dd5233",
"sha256": "8b75d41c2bcce417404afa94787e96ff2ba2c16948bfca06d3e8179d887ec7e4"
},
"downloads": -1,
"filename": "simple_aws_ssm_parameter_store-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "ed91a374fc6fc82c80d09344f0dd5233",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 15435,
"upload_time": "2025-08-18T20:25:39",
"upload_time_iso_8601": "2025-08-18T20:25:39.587135Z",
"url": "https://files.pythonhosted.org/packages/45/4d/d817df4fd5f4ccb40cf42a433c6d126cc5c142f4e63a5e5fdfd5f2024a1e/simple_aws_ssm_parameter_store-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-18 20:25:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MacHu-GWU",
"github_project": "simple_aws_ssm_parameter_store-project",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "boto3",
"specs": [
[
"==",
"1.40.11"
]
]
},
{
"name": "botocore",
"specs": [
[
"==",
"1.40.11"
]
]
},
{
"name": "func-args",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "jmespath",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.9.0.post0"
]
]
},
{
"name": "s3transfer",
"specs": [
[
"==",
"0.13.1"
]
]
},
{
"name": "six",
"specs": [
[
"==",
"1.17.0"
]
]
}
],
"lcname": "simple-aws-ssm-parameter-store"
}
JSON
