Type Annotations for boto3 SSM

1.42.54 · active · verified Thu Apr 09

mypy-boto3-ssm provides comprehensive type annotations for the AWS Boto3 SSM (Systems Manager) client. This library enhances static analysis, improves auto-completion in IDEs like VSCode and PyCharm, and enables early detection of potential runtime errors with type checkers like Mypy. It is currently at version 1.42.54, which aligns with a specific Boto3 version, and is generated using the `mypy-boto3-builder` (version 8.12.0). The project maintains an active release cadence, syncing with Boto3 updates.

Warnings

breaking Support for Python 3.8 has been removed in `mypy-boto3-builder` version 8.12.0 and subsequent generated packages. Users on Python 3.8 or older must upgrade to Python 3.9+ to use the latest `mypy-boto3-ssm` versions.
Fix: Upgrade your Python environment to 3.9 or higher.
breaking The `mypy-boto3` ecosystem migrated to PEP 561 compliant packages in builder version 8.12.0. While this primarily affects how type checkers find stubs, ensure explicit installation of service-specific stub packages (`mypy-boto3-ssm`) rather than relying on `boto3-stubs` for specific services if you encounter import issues.
Fix: Explicitly install `mypy-boto3-ssm` alongside `boto3`. For broader Boto3 typing, `boto3-stubs` is an alternative, but `mypy-boto3-ssm` is for this specific service.
breaking TypeDef naming conventions changed in builder version 8.9.0, typically shortening names (e.g., `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`). While the example refers to a different service, similar renames might affect SSM-related `TypeDef` imports. Always check documentation for specific `TypeDef` names.
Fix: Update your `TypeDef` import paths and names to match the new conventions, referring to the `mypy-boto3-ssm` documentation for specific services.
gotcha `mypy-boto3-ssm` provides only type stubs, not the actual runtime implementation of the AWS SDK. You must install `boto3` separately for your code to execute correctly.
Fix: Always include `pip install boto3` in your project's setup alongside `pip install mypy-boto3-ssm`.
gotcha For the most precise type checking of Boto3 API responses, it is recommended to explicitly import and use the generated `TypeDef` objects (e.g., `GetParameterResultTypeDef`) from `mypy_boto3_ssm.type_defs`. This provides richer type information than generic `dict` annotations.
Fix: Instead of `response: dict = client.get_parameter(...)`, use `from mypy_boto3_ssm.type_defs import MyServiceResultTypeDef; response: MyServiceResultTypeDef = client.get_parameter(...)`.

Install

pip install boto3 mypy-boto3-ssm Install with pip

Imports

SSMClient
```
from mypy_boto3_ssm.client import SSMClient
```
Import the typed client for Boto3 SSM.
GetParameterResultTypeDef
```
from mypy_boto3_ssm.type_defs import GetParameterResultTypeDef
```
Import specific TypedDicts for precise type hints on API response structures.
Session().client("ssm")
While functional, this lacks static type information. For type hints, you should annotate the client variable with `SSMClient`.

Quickstart

This quickstart demonstrates how to get a type-hinted AWS SSM client and retrieve a parameter. It uses explicit type annotations for the client and the response, leveraging the `mypy-boto3-ssm` stubs for static analysis and IDE support. Remember to have `boto3` installed and your AWS credentials configured.

import os
import boto3
from mypy_boto3_ssm.client import SSMClient
from mypy_boto3_ssm.type_defs import GetParameterResultTypeDef

def get_ssm_parameter(name: str) -> str | None:
    # Ensure AWS credentials are available (e.g., via environment variables, ~/.aws/credentials)
    # For local testing, you might need to mock or ensure a valid AWS setup.
    
    # Explicitly type the client for mypy compatibility and IDE autocompletion
    client: SSMClient = boto3.client("ssm")

    try:
        response: GetParameterResultTypeDef = client.get_parameter(Name=name, WithDecryption=True)
        return response.get("Parameter", {}).get("Value")
    except client.exceptions.ParameterNotFound:
        print(f"Parameter '{name}' not found.")
        return None
    except Exception as e:
        print(f"An error occurred: {e}")
        return None

# Example usage (requires an actual AWS SSM parameter and credentials)
# You might need to set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION
# os.environ['AWS_ACCESS_KEY_ID'] = os.environ.get('AWS_ACCESS_KEY_ID', '')
# os.environ['AWS_SECRET_ACCESS_KEY'] = os.environ.get('AWS_SECRET_ACCESS_KEY', '')
# os.environ['AWS_REGION'] = os.environ.get('AWS_REGION', 'us-east-1')

# Example parameter name - replace with one existing in your AWS account
# parameter_name = "/my/test/parameter"
# parameter_value = get_ssm_parameter(parameter_name)
# if parameter_value:
#    print(f"Value of '{parameter_name}': {parameter_value}")
# else:
#    print(f"Could not retrieve value for '{parameter_name}'.")

view raw JSON →