<p align="center">
<!--
<a href="https://app.circleci.com/pipelines/github/jamesabel/awsimple" alt="build">
<img src="https://img.shields.io/circleci/build/gh/jamesabel/awsimple" />
</a>
-->
<a href="https://codecov.io/gh/jamesabel/awsimple" alt="codecov">
<img src="https://img.shields.io/codecov/c/github/jamesabel/awsimple/master" />
</a>
<a href="https://pypi.org/project/awsimple/" alt="pypi">
<img src="https://img.shields.io/pypi/v/awsimple" />
</a>
<a href="https://pypi.org/project/awsimple/" alt="downloads">
<img src="https://img.shields.io/pypi/dm/awsimple" />
</a>
<!--
<a alt="python">
<img src="https://img.shields.io/pypi/pyversions/awsimple" />
</a>
-->
<a alt="license">
<img src="https://img.shields.io/github/license/jamesabel/awsimple" />
</a>
</p>
# AWSimple
*(pronounced A-W-Simple)*
Simple API for basic AWS services such as S3 (Simple Storage Service), DynamoDB (a NoSQL database), SNS (Simple Notification Service),
and SQS (Simple Queuing Service).
Project featured on [PythonBytes Podcast Episode #224](https://pythonbytes.fm/episodes/show/224/join-us-on-a-python-adventure-back-to-1977).
Full documentation available on [Read the Docs](https://awsimple.readthedocs.io/) .
### Features:
- Simple Object Oriented API on top of boto3
- One-line S3 file write, read, and delete
- Automatic S3 retries
- Locally cached S3 accesses
- True file hashing (SHA512) for S3 files (S3's etag is not a true file hash)
- DynamoDB full table scans (with local cache option)
- DynamoDB secondary indexes
- Built-in pagination (e.g. for DynamoDB table scans and queries). Always get everything you asked for.
- Can automatically set SQS timeouts based on runtime data (can also be user-specified)
- Supports moto mock and localstack. Handy for testing and CI.
## Usage
pip install awsimple
## Examples
The example folder has several examples you can customize and run. Instructions are available in [examples](EXAMPLES.md)
### S3
# print string contents of an existing S3 object
s = S3Access(profile_name="testawsimple", bucket="testawsimple").read_string("helloworld.txt")
print(s)
### DynamoDB
dynamodb_access = DynamoDBAccess(profile_name="testawsimple", table_name="testawsimple")
# put an item into DynamoDB
dynamodb_access.put_item({"id": "batman", "city": "Gotham"})
# now get it back
item = dynamodb_access.get_item("id", "batman")
print(item["city"]) # Gotham
## Introduction
`awsimple` is a simple interface into basic AWS services such as S3 (Simple Storage Service) and
DynamoDB (a simple NoSQL database). It has a set of higher level default settings and behavior
that should cover many basic usage models.
## Discussion
AWS's "serverless" resources offer many benefits. You only pay for what you use, easily scale,
and generally have high performance and availability.
While AWS has many varied services with extensive flexibility, using it for more straight-forward
applications is sometimes a daunting task. There are access modes that are probably not requried
and some default behaviors are not best for common usages. `awsimple` aims to create a higher
level API to AWS services (such as S3, DynamoDB, SNS, and SQS) to improve programmer productivity.
## S3
`awsimple` calculates the local file hash (sha512) and inserts it into the S3 object metadata. This is used
to test for file equivalency.
## Caching
S3 objects and DynamoDB tables can be cached locally to reduce network traffic, minimize AWS costs,
and potentially offer a speedup.
DynamoDB cached table scans are particularly useful for tables that are infrequently updated.
## What`awsimple` Is Not
- `awsimple` is not necessarily the most memory and CPU efficient
- `awsimple` does not provide cost monitoring hooks
- `awsimple` does not provide all the options and features that the regular AWS API (e.g. boto3) does
## Updates/Releases
3.x.x - Cache life for cached DynamoDB scans is now based on most recent table modification time (kept in a separate
table). Explict cache life is no longer required (parameter has been removed).
## Testing using moto mock and localstack
moto mock-ing can improve performance and reduce AWS costs. `awsimple` supports both moto mock and localstack.
In general, it's recommended to develop with mock and finally test with the real AWS services.
Select via environment variables:
- AWSIMPLE_USE_MOTO_MOCK=1 # use moto
- AWSIMPLE_USE_LOCALSTACK=1 # use localstack
### Test Time
| Method | Test Time (seconds) | Speedup (or slowdown) | Comment |
|------------|---------------------|-----------------------|-----------------|
| AWS | 462.65 | 1x | baseline |
| mock | 40.46 | 11x | faster than AWS |
| localstack | 2246.82 | 0.2x | slower than AWS |
System: Intel® Core™ i7 CPU @ 3.47GHz, 32 GB RAM
## Contributing
Contributions are welcome, and more information is available in the [contributing guide](CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/jamesabel/awsimple",
"name": "awsimple",
"maintainer": "",
"docs_url": null,
"requires_python": ">3.10",
"maintainer_email": "",
"keywords": "aws,cloud,storage,database,dynamodb,s3",
"author": "abel",
"author_email": "j@abel.co",
"download_url": "https://github.com/jamesabel/awsimple",
"platform": null,
"description": "\r\n<p align=\"center\">\r\n <!--\r\n <a href=\"https://app.circleci.com/pipelines/github/jamesabel/awsimple\" alt=\"build\">\r\n <img src=\"https://img.shields.io/circleci/build/gh/jamesabel/awsimple\" />\r\n </a>\r\n -->\r\n <a href=\"https://codecov.io/gh/jamesabel/awsimple\" alt=\"codecov\">\r\n <img src=\"https://img.shields.io/codecov/c/github/jamesabel/awsimple/master\" />\r\n </a>\r\n <a href=\"https://pypi.org/project/awsimple/\" alt=\"pypi\">\r\n <img src=\"https://img.shields.io/pypi/v/awsimple\" />\r\n </a>\r\n <a href=\"https://pypi.org/project/awsimple/\" alt=\"downloads\">\r\n <img src=\"https://img.shields.io/pypi/dm/awsimple\" />\r\n </a>\r\n <!--\r\n <a alt=\"python\">\r\n <img src=\"https://img.shields.io/pypi/pyversions/awsimple\" />\r\n </a>\r\n -->\r\n <a alt=\"license\">\r\n <img src=\"https://img.shields.io/github/license/jamesabel/awsimple\" />\r\n </a>\r\n</p>\r\n\r\n# AWSimple\r\n\r\n*(pronounced A-W-Simple)*\r\n\r\nSimple API for basic AWS services such as S3 (Simple Storage Service), DynamoDB (a NoSQL database), SNS (Simple Notification Service), \r\nand SQS (Simple Queuing Service).\r\n\r\nProject featured on [PythonBytes Podcast Episode #224](https://pythonbytes.fm/episodes/show/224/join-us-on-a-python-adventure-back-to-1977).\r\n\r\nFull documentation available on [Read the Docs](https://awsimple.readthedocs.io/) .\r\n\r\n### Features:\r\n\r\n- Simple Object Oriented API on top of boto3\r\n\r\n- One-line S3 file write, read, and delete\r\n\r\n- Automatic S3 retries\r\n\r\n- Locally cached S3 accesses\r\n\r\n- True file hashing (SHA512) for S3 files (S3's etag is not a true file hash)\r\n\r\n- DynamoDB full table scans (with local cache option)\r\n\r\n- DynamoDB secondary indexes\r\n\r\n- Built-in pagination (e.g. for DynamoDB table scans and queries). Always get everything you asked for.\r\n\r\n- Can automatically set SQS timeouts based on runtime data (can also be user-specified)\r\n\r\n- Supports moto mock and localstack. Handy for testing and CI.\r\n\r\n\r\n## Usage\r\n\r\n pip install awsimple\r\n\r\n## Examples\r\n\r\nThe example folder has several examples you can customize and run. Instructions are available in [examples](EXAMPLES.md)\r\n\r\n### S3\r\n\r\n # print string contents of an existing S3 object\r\n s = S3Access(profile_name=\"testawsimple\", bucket=\"testawsimple\").read_string(\"helloworld.txt\")\r\n print(s)\r\n\r\n### DynamoDB\r\n\r\n dynamodb_access = DynamoDBAccess(profile_name=\"testawsimple\", table_name=\"testawsimple\")\r\n\r\n # put an item into DynamoDB\r\n dynamodb_access.put_item({\"id\": \"batman\", \"city\": \"Gotham\"})\r\n\r\n # now get it back\r\n item = dynamodb_access.get_item(\"id\", \"batman\")\r\n print(item[\"city\"]) # Gotham\r\n\r\n## Introduction\r\n\r\n`awsimple` is a simple interface into basic AWS services such as S3 (Simple Storage Service) and\r\nDynamoDB (a simple NoSQL database). It has a set of higher level default settings and behavior\r\nthat should cover many basic usage models.\r\n\r\n## Discussion\r\n\r\nAWS's \"serverless\" resources offer many benefits. You only pay for what you use, easily scale, \r\nand generally have high performance and availability.\r\n\r\nWhile AWS has many varied services with extensive flexibility, using it for more straight-forward \r\napplications is sometimes a daunting task. There are access modes that are probably not requried \r\nand some default behaviors are not best for common usages. `awsimple` aims to create a higher \r\nlevel API to AWS services (such as S3, DynamoDB, SNS, and SQS) to improve programmer productivity.\r\n\r\n\r\n## S3\r\n\r\n`awsimple` calculates the local file hash (sha512) and inserts it into the S3 object metadata. This is used\r\nto test for file equivalency.\r\n\r\n## Caching\r\n\r\nS3 objects and DynamoDB tables can be cached locally to reduce network traffic, minimize AWS costs, \r\nand potentially offer a speedup.\r\n\r\nDynamoDB cached table scans are particularly useful for tables that are infrequently updated.\r\n\r\n## What`awsimple` Is Not\r\n\r\n- `awsimple` is not necessarily the most memory and CPU efficient\r\n\r\n- `awsimple` does not provide cost monitoring hooks\r\n\r\n- `awsimple` does not provide all the options and features that the regular AWS API (e.g. boto3) does\r\n\r\n## Updates/Releases\r\n\r\n3.x.x - Cache life for cached DynamoDB scans is now based on most recent table modification time (kept in a separate \r\ntable). Explict cache life is no longer required (parameter has been removed).\r\n\r\n## Testing using moto mock and localstack\r\n\r\nmoto mock-ing can improve performance and reduce AWS costs. `awsimple` supports both moto mock and localstack.\r\nIn general, it's recommended to develop with mock and finally test with the real AWS services.\r\n\r\nSelect via environment variables:\r\n\r\n - AWSIMPLE_USE_MOTO_MOCK=1 # use moto\r\n - AWSIMPLE_USE_LOCALSTACK=1 # use localstack\r\n\r\n### Test Time\r\n\r\n| Method | Test Time (seconds) | Speedup (or slowdown) | Comment |\r\n|------------|---------------------|-----------------------|-----------------|\r\n| AWS | 462.65 | 1x | baseline |\r\n| mock | 40.46 | 11x | faster than AWS |\r\n| localstack | 2246.82 | 0.2x | slower than AWS |\r\n\r\nSystem: Intel® Core™ i7 CPU @ 3.47GHz, 32 GB RAM\r\n\r\n## Contributing\r\n\r\nContributions are welcome, and more information is available in the [contributing guide](CONTRIBUTING.md).\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Simple AWS API for S3, DynamoDB, SNS, and SQS",
"version": "3.3.0",
"project_urls": {
"Documentation": "https://awsimple.readthedocs.io/",
"Download": "https://github.com/jamesabel/awsimple",
"Homepage": "https://github.com/jamesabel/awsimple"
},
"split_keywords": [
"aws",
"cloud",
"storage",
"database",
"dynamodb",
"s3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "344a3c12253b0ced48bedf3b01274e925ffbad786fe7750b19f6bd85eb37b2f9",
"md5": "c370967e42876d53a1e1616ccf81c8f3",
"sha256": "80620e34b86aa2bccf7b8167b95bb66390ca18660100b7f18c18586c9cd45291"
},
"downloads": -1,
"filename": "awsimple-3.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c370967e42876d53a1e1616ccf81c8f3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.10",
"size": 34468,
"upload_time": "2024-03-06T01:31:15",
"upload_time_iso_8601": "2024-03-06T01:31:15.815200Z",
"url": "https://files.pythonhosted.org/packages/34/4a/3c12253b0ced48bedf3b01274e925ffbad786fe7750b19f6bd85eb37b2f9/awsimple-3.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-06 01:31:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jamesabel",
"github_project": "awsimple",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "awsimple"
}
JSON
