Metadata-Version: 2.3
Name: simple_aws_ssm_parameter_store
Version: 0.1.1
Summary: A Pythonic wrapper library for AWS SSM Parameter Store with enhanced error handling, existence testing, idempotent operations, and comprehensive tag management.
License: MIT
Author: Sanhe Hu
Author-email: husanhe@email.com
Maintainer: Sanhe Hu
Maintainer-email: husanhe@email.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Provides-Extra: auto
Provides-Extra: dev
Provides-Extra: doc
Provides-Extra: test
Requires-Dist: Sphinx (>=7.4.7,<8.0.0) ; extra == "doc"
Requires-Dist: boto3 (>=1.35.99,<2.0.0)
Requires-Dist: boto3-stubs[ssm] (>=1.35.99,<2.0.0) ; extra == "dev"
Requires-Dist: build (>=1.2.1,<2.0.0) ; extra == "dev"
Requires-Dist: docfly (==3.0.0) ; extra == "doc"
Requires-Dist: func_args (>=1.0.1,<2.0.0)
Requires-Dist: furo (==2024.8.6) ; extra == "doc"
Requires-Dist: ipython (>=8.18.1,<8.19.0) ; extra == "doc"
Requires-Dist: moto (>=5.0.0,<6.0.0) ; extra == "test"
Requires-Dist: nbsphinx (>=0.8.12,<1.0.0) ; extra == "doc"
Requires-Dist: pygments (>=2.18.0,<3.0.0) ; extra == "doc"
Requires-Dist: pytest (>=8.2.2,<9.0.0) ; extra == "test"
Requires-Dist: pytest-cov (>=6.0.0,<7.0.0) ; extra == "test"
Requires-Dist: rich (>=13.8.1,<14.0.0) ; extra == "dev"
Requires-Dist: rstobj (==1.2.1) ; extra == "doc"
Requires-Dist: sphinx-copybutton (>=0.5.2,<1.0.0) ; extra == "doc"
Requires-Dist: sphinx-design (>=0.6.1,<1.0.0) ; extra == "doc"
Requires-Dist: sphinx-jinja (>=2.0.2,<3.0.0) ; extra == "doc"
Requires-Dist: twine (>=6.0.0,<7.0.0) ; extra == "dev"
Requires-Dist: wheel (>=0.45.0,<1.0.0) ; extra == "dev"
Project-URL: Changelog, https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/blob/main/release-history.rst
Project-URL: Documentation, https://simple-aws-ssm-parameter-store.readthedocs.io/en/latest/
Project-URL: Download, https://pypi.org/pypi/simple-aws-ssm-parameter-store#files
Project-URL: Homepage, https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project
Project-URL: Issues, https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project/issues
Project-URL: Repository, https://github.com/MacHu-GWU/simple_aws_ssm_parameter_store-project
Description-Content-Type: text/x-rst


.. 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. 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

