aioboto3

Common errors

• ModuleNotFoundError: No module named 'aioboto3'

  cause The 'aioboto3' library is not installed in the Python environment.
  fix pip install aioboto3

• AttributeError: 'ResourceCreatorContext' object has no attribute 'Table'

  cause The 'resource' method in 'aioboto3' is asynchronous and needs to be awaited.
  fix dynamodb = await aioboto3.Session().resource('dynamodb')

• AttributeError: module 'aiobotocore' has no attribute 'AioSession'

  cause The 'AioSession' attribute is not present in the 'aiobotocore' module, possibly due to version incompatibility.
  fix Ensure compatible versions of 'aioboto3' and 'aiobotocore' are installed, or downgrade 'aioboto3' to a version where 'AioSession' is available.

• AttributeError: 'ClientCreatorContext' object has no attribute 'invoke_endpoint'

  cause The 'client' method in 'aioboto3' is asynchronous and needs to be awaited.
  fix sagemaker_client = await aioboto3.Session().client('sagemaker-runtime')

• RuntimeWarning: coroutine '...' was never awaited

  cause An asynchronous function (coroutine) was called, but its execution was not properly initiated using the `await` keyword or by `asyncio.run()`, meaning the coroutine object was created but never executed.
  fix Ensure all calls to `async` functions within an `async` context are prefixed with `await`. If calling from synchronous code, wrap the coroutine call with `asyncio.run()`.

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.
• gotcha aioboto3 could not find AWS credentials. This often manifests as `botocore.exceptions.NoCredentialsError: Unable to locate credentials` when attempting to interact with AWS services.
  Fix: Ensure AWS credentials are correctly configured in your environment. This can be done via environment variables (e.g., `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`), shared credential files (`~/.aws/credentials`), or IAM roles (for EC2 instances or ECS tasks).
• gotcha Unable to locate AWS credentials. Ensure your AWS credentials are configured via environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY), shared credentials file (~/.aws/credentials), or IAM roles/profiles.
  Fix: Configure AWS credentials in your environment. Refer to the AWS documentation on configuring the AWS CLI and SDKs for detailed instructions.

Install

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

Imports

• Session
  wrong:

  import aioboto3; client = aioboto3.client('s3')

  correct:

  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())