finalsa-sqs-client
Thin, typed wrapper around AWS SQS using boto3 with a simple in-memory test implementation.
- Python 3.10+
- Adds W3C trace headers to all messages by default (traceparent, tracestate)
- Accepts dict or JSON string payloads
- Returns a convenient
SqsReponsemodel with flattened message attributes
Installation
Using pip or uv:
pip install finalsa-sqs-client
# or
uv add finalsa-sqs-client
Requires valid AWS credentials for the default boto3 client (env vars, config file, or IAM role).
Quick start
from finalsa.sqs.client import SqsServiceImpl, SqsException
svc = SqsServiceImpl()
# Resolve a queue URL by name (helper)
queue_url = svc.get_queue_url("my-queue")
# Send a JSON payload (dict) with optional custom attributes
svc.send_message(queue_url, {"hello": "world"}, {"tenant": "acme"})
# Receive up to 10 messages and delete them
messages = svc.receive_messages(queue_url, max_number_of_messages=10, wait_time_seconds=1)
for msg in messages:
print("body:", msg.body) # raw JSON string
print("attrs:", msg.message_attributes) # flattened: {"traceparent": "...", ...}
svc.delete_message(queue_url, msg.receipt_handle)
# Other helpers
arn = svc.get_queue_arn(queue_url)
attrs = svc.get_queue_attributes(queue_url)
Errors are raised as SqsException wrapping the underlying boto3 error when applicable.
Message attributes and tracing
- Custom attributes can be passed as a simple dict of strings:
{"key": "value"}. - The client adds two trace headers automatically to every send:
traceparenttracestate
- When receiving messages, attributes are returned flattened into a
dict[str, str]onSqsReponse.message_attributes.
Example sending raw string JSON and custom attributes:
svc.send_raw_message(queue_url, '{"a":1}', {"source": "ingestor"})
In-memory test service
For local tests or offline development, use the built-in, in-memory implementation:
from finalsa.sqs.client import SqsServiceTest
svc = SqsServiceTest()
svc.send_message("test-queue", {"x": 1})
msgs = svc.receive_messages("test-queue")
assert len(msgs) == 1
svc.delete_message("test-queue", msgs[0].receipt_handle)
Notes:
SqsServiceTestkeeps messages in process memory keyed by the queue URL/name you pass.- It also injects the same trace attributes as the real client so behavior matches production closely.
API overview
The primary entry points are exported from finalsa.sqs.client:
SqsService: abstract interfaceSqsServiceImpl: boto3-backed implementationSqsServiceTest: in-memory implementation for testsSqsException: error wrapper
Key methods (see docstrings for details):
receive_messages(queue_url, max_number_of_messages=1, wait_time_seconds=1) -> list[SqsReponse]send_message(queue_url, payload: dict, message_attributes: dict | None = None) -> Nonesend_raw_message(queue_url, data: dict | str, message_attributes: dict | None = None) -> Nonedelete_message(queue_url, receipt_handle) -> Noneget_queue_arn(queue_url) -> strget_queue_attributes(queue_url) -> dictget_queue_url(queue_name) -> str
Payload handling:
- Dict payloads are serialized with orjson (compact) before sending.
- String payloads are sent as-is.
Credentials and configuration
SqsServiceImpl uses the default boto3.client('sqs'). Configure credentials/region via any standard boto3 method:
- Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, ...)
- AWS config/credentials files
- IAM role when running in AWS
Development
Run tests with uv (recommended):
uv sync
uv run pytest -q
Or with plain pip:
python -m venv .venv && source .venv/bin/activate
pip install -e .[test]
pytest -q
License
MIT – see LICENSE.md.
Metadata
Release files for finalsa-sqs-client 2.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| finalsa_sqs_client-2.1.1.tar.gz | 6.1 kB | Without provenance | Details for finalsa_sqs_client-2.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| finalsa_sqs_client-2.1.1-py3-none-any.whl | Python 3 | none | any | Details for finalsa_sqs_client-2.1.1-py3-none-any.whl |
Total release size: 15.0 kB
Release files / finalsa_sqs_client-2.1.1.tar.gz
| Download URL | finalsa_sqs_client-2.1.1.tar.gz |
|---|---|
| Size | 6.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
01c67e577d639d16dfa97209961d302ec0a4fc06e5def11ae95281c8da6cc1c1
|
|
BLAKE2b-256 checksum How to use checksums |
684cb4e1d82e2a6c283a45ace1d34b28a537084277b4b3fa9e0715bf07339a58
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.8.12
|
Release files / finalsa_sqs_client-2.1.1-py3-none-any.whl
| Download URL | finalsa_sqs_client-2.1.1-py3-none-any.whl |
|---|---|
| Size | 9.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bce94a20c6b17726e88b4be2f61632f23eb20722aaec2ed8dc85a21bd8f3be81
|
|
BLAKE2b-256 checksum How to use checksums |
fd66d68be70b38534248c5380a0bf2f87bc641ee2403e06c079fd1b6120144a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.8.12
|
Security for finalsa-sqs-client 2.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.