🧩 pyawsmock - Local AWS Mock Framework
🧠 A lightweight, extensible Python package that mocks AWS services locally for development and testing - with real AWS delegation when needed.
🚀 Overview
pyawsmock emulates popular AWS services locally, allowing developers to test AWS-dependent applications without
needing cloud connectivity. It's boto3-compatible, automatically delegating API calls to the real AWS SDK when
using non-local regions.
✅ Currently Supported Services
| Service | Description |
|---|---|
| 🪣 S3 | Object storage mock supporting uploads, downloads, metadata, and checksums. |
| ⚙️ SSM Parameter Store | Local emulation of AWS SSM Parameters with versioning, labels, and encryption. |
| 🧱 CodeArtifact | Domain & repository management with package versioning and mock endpoints. |
| 🌐 CloudFront | Create and manage distributions and origin access identities locally. |
| 📬 SQS | Local emulation of SQS with FIFO support. |
🧠 Key Features
🧭 Local vs AWS Delegation
- Regions starting with
local-*automatically use local mock services. - Other regions transparently delegate calls to real AWS using
boto3.
💾 Persistent & Temporary Storage
- Persistent mode — data is stored on disk (for long-term local environments).
- Temporary mode — uses an in-memory or temp directory;
cleanup()removes it automatically.
🕓 Audit & Metadata
- Tracks all operations with timestamps.
- Simulates IAM users (
mock-user) andarn:mockidentifiers. - Default mock AWS Account ID:
000000000000.
🔐 SecureString & Encryption Simulation
- For SSM,
SecureStringvalues are stored base64-encoded. - Retrieval with
WithDecryption=Trueautomatically decodes them.
🪶 Lightweight & Extensible
- Minimal dependencies (
boto3,filelock,crcmod). - Modular mock architecture — easy to extend to new AWS services.
⚙️ Installation
📦 From PyPI
pip install pyawsmock
🧩 From GitHub
pip install git+https://github.com/coldsofttech/pyawsmock.git
Dependencies
boto3~=1.40.55filelock~=3.20.0crcmod~=1.7
boto3is required for delegation to real AWS services.
🧰 Quick Start Example
from pyawsmock import configure_mock, client, cleanup_mock
# 1️⃣ Configure mock mode
configure_mock(mode="persistent", path="./local_aws") # Persistent local store
# or
configure_mock(mode="temporary") # Temporary store
# 2️⃣ Create a local client (SSM)
ssm = client("ssm", region_name="local-eu-west-1")
# 3️⃣ Use it just like boto3
ssm.put_parameter(Name="/demo/key", Value="demo_value", Type="String")
response = ssm.get_parameter(Name="/demo/key")
print(response["Parameter"]["Value"]) # Output: demo_value
# 4️⃣ Cleanup (only for temporary mode)
cleanup_mock()
⚡ All clients (SSM, S3, SQS, CodeArtifact, CloudFront) use the same interface as boto3. Switching between real AWS and local mock only depends on the region.
🧩 Supported Methods
| Service | Supported API Calls |
|---|---|
| ⚙️ SSM (Parameter Store) | put_parameter, get_parameter, get_parameters, delete_parameter, label_parameter_version, unlabel_parameter_version, describe_parameters, get_parameters_by_path, get_parameter_history |
| 🪣 S3 | create_bucket, upload_file, download_file, get_object, create_bucket_metadata_configuration, update_bucket_metadata_inventory_table_configuration, delete_bucket_metadata_configuration, etc. |
| 🧱 CodeArtifact | create_domain, create_repository, publish_package_version, list_packages, delete_package, get_authorization_token, get_repository_endpoint, etc. |
| 🌐 CloudFront | create_distribution, get_distribution, get_distribution_config, update_distribution, delete_distribution, etc. |
| 📬 SQS | create_queue, get_queue_url, set_queue_attributes, get_queue_attributes, list_queues, purge_queue, etc. |
🧩 More services coming soon: API Gateway, DynamoDB, Lambda, CloudWatch, Config, and **CloudTrail **.
⚠️ Known Limitations
- IAM, authentication, and permissions are not enforced.
- S3 multipart uploads and full versioning are not implemented yet.
- CodeArtifact currently supports only generic asset types and HTTP endpoints.
- CloudFront distribution behavior is limited to configuration storage only.
- SQS automatic background timers for
DelaySecondsandVisibilityTimeoutcurrently do not exist.
🧭 Roadmap
| Status | Feature |
|---|---|
| ✅ | SSM, S3, SQS, CodeArtifact, CloudFront support |
| 🚧 | API Gateway, DynamoDB, Lambda, CloudWatch mocks |
| 🚧 | IAM simulation with multiple mock users |
| 🕓 | Enhanced audit logging & metrics |
| 🧩 | Multi-account & multi-region persistence |
🤝 Contributing
Contributions are welcome! To contribute:
- Fork the repo
- Create a feature branch
- Add tests and update docs
- Submit a pull request
⚖️ License
Metadata
Release files for pyawsmock 0.1.4
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 |
|---|---|---|---|---|
| pyawsmock-0.1.4.tar.gz | 33.1 kB | Without provenance | Details for pyawsmock-0.1.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyawsmock-0.1.4-py3-none-any.whl | Python 3 | none | any | Details for pyawsmock-0.1.4-py3-none-any.whl |
Total release size: 70.1 kB
Release files / pyawsmock-0.1.4.tar.gz
| Download URL | pyawsmock-0.1.4.tar.gz |
|---|---|
| Size | 33.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
35e74945dddaba48af7ccfb1f73d8df6faf35b23a8d048d3d1746fb6acf68a62
|
|
BLAKE2b-256 checksum How to use checksums |
2728e8006e7b1b7b3e4781b3939e68f6465f949f821d82bdb77e1eaf6e7cf9aa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.18
|
Release files / pyawsmock-0.1.4-py3-none-any.whl
| Download URL | pyawsmock-0.1.4-py3-none-any.whl |
|---|---|
| Size | 37.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
603fd5fecd8c1ce76ef345871f674e3a0a001c3e127d27543a862fae2bf32da9
|
|
BLAKE2b-256 checksum How to use checksums |
046d3065db2b1b1f41e03e58255d56d3cdf6cdd5fdcf10ba57efd2bbe86ddbd2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.18
|
Security for pyawsmock 0.1.4
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.