aioboto3

15.5.0 · active · verified Sat Mar 28

aioboto3 is an asynchronous wrapper for boto3, the Amazon Web Services (AWS) SDK for Python. It allows developers to interact with AWS services using Python's `async/await` syntax, leveraging the `aiobotocore` library for its asynchronous backend. This enables non-blocking I/O operations with AWS, ideal for modern async applications. The current version is 15.5.0, with frequent releases often aligned with updates to its underlying dependencies.

Warnings

breaking Breaking Change in v9: Direct calls to `aioboto3.resource()` and `aioboto3.client()` are no longer available. You must first create a `Session` object and then use `session.client()` or `session.resource()`.
Fix: Replace `aioboto3.client('service')` with `session = aioboto3.Session(); async with session.client('service') as client:`
breaking Breaking Change in v9/v8.0.0+: `client` and `resource` methods (obtained from a session) must now be used as asynchronous context managers (`async with`). This change aligns with `aiobotocore` 1.0.1+ behavior.
Fix: Ensure all `session.client()` and `session.resource()` calls are wrapped in an `async with` statement, e.g., `async with session.client('s3') as s3_client:`.
breaking Breaking Change in v11: The `S3Transfer` configuration passed into S3 `upload_file` and `download_file` methods has been updated to match `boto3`'s behavior, which might require adjustments if you were passing custom transfer configurations.
Fix: Review S3 `upload_file` and `download_file` calls for custom `S3Transfer` configurations and adapt them to the `boto3`-aligned structure.
gotcha Service-specific resource objects (e.g., `s3.Bucket`, `dynamo_resource.Table`) must be `await`ed when instantiated, as their creation is an asynchronous operation.
Fix: Always use `await` when getting a specific resource object, e.g., `bucket = await s3_resource.Bucket('mybucket')` or `table = await dynamodb_resource.Table('my_table')`.
gotcha For long-running processes like web servers, directly using `async with session.client(...)` per request can introduce overhead. For persistent clients, an `AsyncExitStack` or similar pattern is recommended to manage the context manager lifecycle.
Fix: For persistent clients in web servers, manage client/resource lifecycle using `AsyncExitStack` (e.g., in FastAPI's startup/shutdown events) to ensure clients are opened once and properly closed.

Install

pip install aioboto3 Standard Installation
pip install aioboto3[s3cse] With S3 Client-Side Encryption

Imports

Session
```
from aioboto3 import Session
```
Top-level `aioboto3.client` and `aioboto3.resource` were removed in v9. You must create a Session first, then use `session.client()` or `session.resource()`.

Quickstart

This quickstart demonstrates creating an asynchronous DynamoDB resource, creating a table (if it doesn't exist), inserting an item, querying it, and finally deleting the table. Ensure your AWS credentials and default region are configured in your environment (e.g., via `~/.aws/credentials` or environment variables like `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`).

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

async def main():
    aws_region = os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')
    session = Session()
    async with session.resource('dynamodb', region_name=aws_region) as dynamodb_resource:
        table_name = 'my_async_table'
        # Check if table exists, create if not (simplified for quickstart)
        try:
            await dynamodb_resource.Table(table_name).wait_until_exists()
            print(f"Table '{table_name}' already exists.")
        except Exception:
            print(f"Creating table '{table_name}'...")
            table = await dynamodb_resource.create_table(
                TableName=table_name,
                KeySchema=[
                    {'AttributeName': 'pk', 'KeyType': 'HASH'}
                ],
                AttributeDefinitions=[
                    {'AttributeName': 'pk', 'AttributeType': 'S'}
                ],
                BillingMode='PAY_PER_REQUEST'
            )
            await table.wait_until_exists()
            print(f"Table '{table_name}' created successfully.")
            table = await dynamodb_resource.Table(table_name)

        table = await dynamodb_resource.Table(table_name)
        
        print("Putting item...")
        await table.put_item(
            Item={'pk': 'test1', 'data': 'async_data_value'}
        )
        print("Item put.")

        print("Querying item...")
        result = await table.query(
            KeyConditionExpression=Key('pk').eq('test1')
        )
        print("Query result:", result['Items'])

        # Clean up (optional, for demonstration)
        print(f"Deleting table '{table_name}'...")
        await table.delete()
        await table.wait_until_not_exists()
        print(f"Table '{table_name}' deleted.")

if __name__ == '__main__':
    asyncio.run(main())

view raw JSON →