You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
Alexey Berezhnoy f0eb8df83b Added abort of multipart upload when file read error 2 years ago
.github Initial commit 4 years ago
aioboto3 Added abort of multipart upload when file read error 2 years ago
docs Address change requests + remove object exists example as it seems to not be optimal 2 years ago
resources/S3-CSE Added test cases for CSE 3 years ago
tests Added tests for auto_properties and async resource waiters 2 years ago
.bumpversion.cfg Bump version: 6.4.0 → 6.4.1 2 years ago
.editorconfig Initial commit 4 years ago
.gitignore Started adding symmetric CSE support 3 years ago
.pyup.yml Added pyup config 2 years ago
.readthedocs.yml 2nd attempt at fix 3 years ago
.travis.yml Removed typehints that break py35 3 years ago
AUTHORS.rst Initial commit 4 years ago
CONTRIBUTING.rst Update CONTRIBUTING steps 3 years ago
HISTORY.rst Fixed RST 2 years ago
LICENSE Changed license, cleaned up some flake 4 years ago
MANIFEST.in Initial commit 4 years ago
Makefile Changed license, cleaned up some flake 4 years ago
README.rst fix typo in README 2 years ago
requirements_dev.txt Update deps 2 years ago
setup.cfg Bump version: 6.4.0 → 6.4.1 2 years ago
setup.py Bump version: 6.4.0 → 6.4.1 2 years ago
tox.ini Add Python 3.7 to Travis and Tox 3 years ago
travis_pypi_setup.py Initial commit 4 years ago

README.rst

========================
Async AWS SDK for Python
========================


.. image:: https://img.shields.io/pypi/v/aioboto3.svg
:target: https://pypi.python.org/pypi/aioboto3

.. image:: https://travis-ci.com/terrycain/aioboto3.svg?branch=master
:target: https://travis-ci.com/terrycain/aioboto3

.. image:: https://readthedocs.org/projects/aioboto3/badge/?version=latest
:target: https://aioboto3.readthedocs.io
:alt: Documentation Status

.. image:: https://pyup.io/repos/github/terrycain/aioboto3/shield.svg
:target: https://pyup.io/repos/github/terrycain/aioboto3/
:alt: Updates


This package is mostly just a wrapper combining the great work of boto3_ and aiobotocore_.

aiobotocore allows you to use near enough all of the boto3 client commands in an async manner just by prefixing the command with `await`.

With aioboto3 you can now use the higher level APIs provided by boto3 in an asynchronous manner. Mainly I developed this as I wanted to use the boto3 dynamodb Table object in some async
microservices.

While all resources in boto3 should work I havent tested them all, so if what your after is not in the table below then try it out, if it works drop me an issue with a simple test case
and I'll add it to the table.

+---------------------------+--------------------+
| Services | Status |
+===========================+====================+
| DynamoDB Service Resource | Tested and working |
+---------------------------+--------------------+
| DynamoDB Table | Tested and working |
+---------------------------+--------------------+
| S3 | Working |
+---------------------------+--------------------+
| Kinesis | Working |
+---------------------------+--------------------+
| SSM Parameter Store | Working |
+---------------------------+--------------------+
| Athena | Working |
+---------------------------+--------------------+


Example
-------

Simple example of using aioboto3 to put items into a dynamodb table

.. code-block:: python

import asyncio
import aioboto3
from boto3.dynamodb.conditions import Key


async def main():
async with aioboto3.resource('dynamodb', region_name='eu-central-1') as dynamo_resource:
table = dynamo_resource.Table('test_table')

await table.put_item(
Item={'pk': 'test1', 'col1': 'some_data'}
)

result = await table.query(
KeyConditionExpression=Key('pk').eq('test1')
)

# Example batch write
more_items = [{'pk': 't2', 'col1': 'c1'}, \
{'pk': 't3', 'col1': 'c3'}]
async with table.batch_writer() as batch:
for item_ in more_items:
await batch.put_item(Item=item_)

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

# Outputs:
# [{'col1': 'some_data', 'pk': 'test1'}]


Things that either dont work or have been patched
-------------------------------------------------

As this library literally wraps boto3, its inevitable that some things won't magically be async.

Fixed:

- ``s3_client.download_file*`` This is performed by the s3transfer module. -- Patched with get_object
- ``s3_client.upload_file*`` This is performed by the s3transfer module. -- Patched with custom multipart upload
- ``s3_client.copy`` This is performed by the s3transfer module. -- Patched to use get_object -> upload_fileobject
- ``dynamodb_resource.Table.batch_writer`` This now returns an async context manager which performs the same function
- Resource waiters - You can now await waiters which are part of resource objects, not just client waiters, e.g. ``await dynamodbtable.wait_until_exists()``
- Resource object properties are normally autoloaded, now they are all co-routines and the metadata they come from will be loaded on first await and then cached thereafter.


Amazon S3 Client-Side Encryption
--------------------------------

Boto3 doesn't support AWS client-side encryption so until they do I've added basic support for it. Docs here CSE_

CSE requires the python ``cryptography`` library so if you do ``pip install aioboto3[s3cse]`` that'll also include cryptography.

This library currently supports client-side encryption using KMS-Managed master keys performing envelope encryption
using either AES/CBC/PKCS5Padding or preferably AES/GCM/NoPadding. The files generated are compatible with the Java Encryption SDK
so I will assume they are compatible with the Ruby, PHP, Go and C++ libraries as well.

Non-KMS managed keys are not yet supported but if you have use of that, raise an issue and i'll look into it.



Documentation
-------------

Docs are here - https://aioboto3.readthedocs.io/en/latest/

Examples here - https://aioboto3.readthedocs.io/en/latest/usage.html


Features
========

* Closely mimics the usage of boto3.

Todo
====

* More examples
* Set up docs
* Look into monkey-patching the aws xray sdk to be more async if it needs to be.


Credits
-------

This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
It also makes use of the aiobotocore_ and boto3_ libraries. All the credit goes to them, this is mainly a wrapper with some examples.

.. _aiobotocore: https://github.com/aio-libs/aiobotocore
.. _boto3: https://github.com/boto/boto3
.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
.. _CSE: https://aioboto3.readthedocs.io/en/latest/cse.html