Amazon SNS Extended Client Library for Python

1.0.1 verified Mon Apr 27 auth: no python

Python version of AWS SNS extended client that enables publishing large payload messages (>256KB) via Amazon S3. Current version 1.0.1, release cadence is low (latest release Jan 2022).

pip install amazon-sns-extended-client

Common errors

error botocore.exceptions.ClientError: An error occurred (InvalidParameter) when calling the Publish operation: Invalid parameter: Message too long ↓

cause Message size exceeds the SNS limit of 256KB and the extended client is not configured or used.

fix

Use SNSExtendedClient to automatically store large payloads in S3.

error ImportError: cannot import name 'SNSExtendedClient' from 'amazon_sns_extended_client' ↓

cause Incorrect import path or wrong package version.

fix

Ensure you have installed amazon-sns-extended-client (not sns-extended-client) and import as: from amazon_sns_extended_client import SNSExtendedClient

error botocore.exceptions.ClientError: An error occurred (AccessDenied) when calling the PutObject operation: Access Denied ↓

cause The IAM role or credentials used do not have permission to write to the configured S3 bucket.

fix

Grant s3:PutObject permission on the bucket to the IAM user/role.

Warnings

breaking The library does NOT support FIFO topics - messages are published without message group/deduplication IDs. Attempting to use FIFO topic will cause error. ↓

fix Use standard SNS topics only, or manually implement ordering/deduplication.

gotcha Payloads are uploaded to S3 as individual objects (one per message). This incurs S3 storage and request costs even for small messages if always routed through extended client. ↓

fix Use SNSMessageSizeChecker to conditionally skip S3 for messages under 256KB.

deprecated The library currently uses the legacy 'PayloadSizeThreshold' parameter in configuration; newer AWS SDK versions may deprecate the client object signature. ↓

fix Check AWS SDK compatibility; if needed, use AWS SDK v2 or higher with updated config.

gotcha The S3 bucket must be in the same region as the SNS topic, otherwise publish will fail with cross-region access errors. ↓

fix Ensure bucket and topic are in the same AWS region.

Imports

SNSExtendedClient
wrong
```
from sns_extended_client import SNSExtendedClient
```
correct
```
from amazon_sns_extended_client import SNSExtendedClient
```
Wrong package name: the correct import uses dashes converted to underscores in the module path.

SNSMessageSizeChecker

from amazon_sns_extended_client.sns_message_size_checker import SNSMessageSizeChecker

Quickstart

Initialize the extended client with SNS and S3 clients and a bucket for payload storage.

import boto3
from amazon_sns_extended_client import SNSExtendedClient

topic_arn = os.environ.get('TOPIC_ARN', 'arn:aws:sns:us-east-1:123456789012:MyTopic')
bucket_name = os.environ.get('BUCKET_NAME', 'my-sns-payload-bucket')

sns_client = boto3.client('sns')
s3_client = boto3.client('s3')

extended_client = SNSExtendedClient(sns_client, s3_client, bucket_name)
response = extended_client.publish(
    TopicArn=topic_arn,
    Message='This is a large message that exceeds the 256KB limit if long enough...' * 1000
)
print(response)